How to use Tessellation

The Tessellation Library allows you to to convert a CAD model to a mesh (a set of triangles). A mesh can be usefull for graphic display or mesh based files generation (like obj, vrml, pdf3d, cgr...).
Tesselation module should be used in datakit API context, i.e the function Dtk_API::StartAPI() should be called before any tesselation routine calls.

• Sample to tessellate a Dtk_Body

Tessellation Process

Our tesselation algorithm works roughly in 5 steps.

• Step 1 - Discretization of each surface and boundary in a point cloud, with respect to the user provided precision (the linear tolerance), see Tesselation precision settings .
  

• Step 2 - Computation of a set of triangles from this cloud, with respect to the user provided options (maximum triangle size, maximum size ratio between two neighbor triangles), see Other settings .
  

• Step 3 - Storage of the resulting triangles in a Dtk_mesh.
• Step 4 - Computation of the normals for each mesh vertices.
  

• Step 5 - Computation of the boundaries of each Dtk_mesh_face.
  
  
  

Using the tessellation library

• First, initialize the library with :

  int tess_InitTesselation(Dtk_string inWorkingDirectory,double inTolerance);

  
  
• Adjust some parameters to fit to your usage, see Tesselation settings .

  tess_set_linear(double tol) 
  tess_set_angular(double angle) 
  tess_set_Ratio(double tol)
  tess_set_MaxSize(double tol) )  

  
  
• Call the actual tesselation algorithm on either a Dtk_Body, Dtk_Shell or a Dtk_Face, see How to tesselate each entity .
  
• You can change any options between two tessellation calls.
• At the end, call

  tess_EndTesselation() 

  to deallocate memory.
  
  

How to tesselate each entity

To tesselate a Dtk_Body use tess_BodyToMeshes(). This method returns an array with one mesh per shell contained in the body.
To tesselate a Dtk_Shell use tess_ShellToMesh(). This is usefull to tesselate a body shell per shell. This method is used if you check if the shell is closed or not and you can ajust the result.
To tesselate a Dtk_Face use tess_FaceToMesh(). This is usefull to tesselate a shell face per face. In this case you cannot obtain any connexion beetwen faces.
To tesselate a set of Dtk_Face use tess_FacesArrayToMesh(). This is usefull to store each faces of a body in an array, and tessellate in one pass. This method can be used with surface format where each open shell contain only one face.
You can save an array with Dtk_Face entity , or use the structure Dtk_OrientedFaceStr , that store orientation in addition of face from shell.

Tesselation settings

Tesselation precision settings

A mesh is by definition less precise than its corresponding brep: a surface composed of a triangle set cannot be as "smooth" as its NURBS mathematical definition. Our tesselation module allows you to control this precision with a linear or angular tolerance.

Linear Tolerance
The linear tolerance represents the chordal error, i.e the maximum distance between the reference curve (the brep curve stored in the body) and the approximated mesh. A smaller value produces a denser mesh on curved geometry that is more accurate, but also heavier. Note that this value is dependant to the model size, a smaller model needs a smaller linear tolerance to keep the same precision as a bigger model.

Discretization result for linear tolerance = 0.5mm (green : the exact surface (reference curve), red : resulting mesh). We can see that the maximum distance between the reference curve and the approximated mesh never exceeds 0.5.
To change the linear tolerance use

tess_set_linear(double tol)

To disable linear tolerance use

tess_disableTolLinear()

Angular Tolerance
Angular tolerance is another way to control the resulting mesh precision.
It is the maximum angle between the reference curve (the brep curve stored in the body) and the approximated mesh. This tolerance has the advantage to be independant to the model size.

Angular tolerance represents deviation angle between points (green : exact surface definition, resulting triangle basis)

Discretization result for angular tolerance = 0.104rad (6deg) (green : the exact surface (reference curve), red : resulting mesh). We can see that the maximum angle between the reference curve and the approximated mesh never exceeds 6deg = 0.104rad.
To enable angular tolerance use

tess_set_angular(double angle); // The angle value is in radian !

To disable angular tolerance use

tess_disableTolAngular()

By default, the linear tolerance is enabled alone.
The tolerance value is the second parameter of tess_InitTesselation(Dtk_string inWorkingDirectory,double inTolerance).
Both linear and angular modes can be combined. In such a case, final meshing results will depend on both criterias.

Other settings

You can set the size ratio between two neighbor triangles with tess_set_Ratio(double tol) . A value at 1.0 generates only isosceles triangles

You can set the maximun lenght of a triangle with the function tess_set_MaxSize(double tol);

Miscallenous functions

• By default, the tessellation computes the exact normal value from the original surface, not a normal from the triangle.
  However, you can disable this calculation if the approximation is sufficient for you, by calling :

  tess_ComputeNormalesFromSurface(DTK_FALSE); 

  
  
• In Dtk_mesh, we save the boundaries computed from the vertices for each face, then you can retrieve them with:
  

  void tess_getBoundariesFromMeshFace(const Dtk_MeshPtr &mesh,const Dtk_mesh_face *inFace,Dtk_tab<Dtk_tab<Dtk_PolylinePtr> > &outBoundaries);

  In the array of polylines, the first one is the outer boundary and others represent the inners if they exist. You can desactivate this storage by calling beforehand the following function :

  tess_ComputeBoundariesFromMesh(DTK_FALSE);

  To get current status for this option use :

  int tess_ComputeBoundariesFromMesh();

  this function return DTK_TRUE if enable (Default value) or DTK_FALSE if disable.
  
  
• Special periodical surfaces / springs These surfaces require a more precise method to be tessellated.
  If we detect a surface like a spring, we activate this specific method.
  You can activate this method at any time with

  void set_TesselateSurfaceMethod(int ival); 

  Note that this method is time consuming.
  
  
• Duplicated faces are removed by default, but you can disable this option with :

  void set_tesselationSuppressDuplicateFace(DTK_TRUE); 

  To get current status for this option use :

  Dtk_bool get_tesselationSuppressDuplicateFace(); 

  
  
• Some formats contain a tolerance for the edge , but this value is neither mandatory nor necessarily relevant. If you want to use this value you need to use

  void CheckUseEdgeTolerance(DTK_TRUE); 

  If the tolerance value read in the part is lower than tolerance value defined previously, this value is used
  To get current status for this option use :

  Dtk_bool CheckUseEdgeTolerance();  

  
  
• Sometime surfaces with various curvatures can be correctly tessellate only with much lower linear tolerance values, in this case it is better to use angular value, but if you want or need linear value, the best way is to temporarily divide the surface at the curvature.
  In this case use the function :

  void set_tesselation_activateSplitMode(const int inmode, const double inratio); 

  • inmode can be :
    • no split ( default value )
    • split based on surface curvature
    • split based on great nodal sequence variation
      
  • inratio is value limit to split face
    depends of mode selected ( curvature or nodal sequence ) equal to the value for curvature or variation between 2 values for nodal sequence, triggering the split.

To get current status for this option use :

void get_tesselation_activateSplitMode(int &outmode, double &outratio);  

To disable the split method after use :

void reinit_SplitMode(); 

WARNING : this method is time-consuming and will be used for special part like turbine blades

• You can dump an some Dtk_mesh into a Stl file with the following methods :
  
  • First, initialise the dump with :

    int init_stl_write(Dtk_string inStlFileName); 

    
    
  • you dump each Dtk_mesh with :

    void write_mesh_solid(const Dtk_MeshPtr &tm)   

    
    
  • you close the stl file with :

    int end_stl_fic(int *ient);  

    
    
    

• To get tesselation status :

  Dtk_ErrorStatus TesselationIsStarted();  

  
  return can be :
  • dtkNoError tesselation is ready
    
  • dtkTessellationNotStarted if tesselation not started
    

For other information, do not hesitate to contact us.

Relationship between Dtk_mesh and Dtk_BodyPtr after tessellation

After using one of the following tessellation methods :

• tess_BodyToMeshes(const Dtk_BodyPtr& inBodyToWrite ,Dtk_tab<Dtk_mesh> & outMeshes,Dtk_tab<Dtk_Int32> & outIsSolid) tess_BodyToMeshes()
  
• tess_FaceToMesh(Dtk_FacePtr &inTabFace,Dtk_MeshPtr &outMesh) tess_FaceToMesh()
  
• tess_ShellToMesh(const Dtk_ShellPtr &inShell, Dtk_MeshPtr &outMesh, Dtk_Int32 *outIsSolid) tess_ShellToMesh()
  You can retrieve associations between Dtk_mesh_face and Dtk_FacePtr and between Edge and mesh boundary with the following code :
  

  void check_id_faces(Dtk_MeshPtr &outMesh,Dtk_BodyPtr TmpBody)
  {
       Dtk_Size_t i,nb,k,nb3,l,nb4,m;
       Dtk_ID ident,ident2;
       Dtk_FacePtr face;
       Dtk_InfoPtr info;
       Dtk_mesh_face *mFace;
       Dtk_Size_t nbMeshFaces = outMesh->get_nb_mesh_face();
   
       for(i = 0 ; i < nbMeshFaces ; ++i)
       {
            // First Step ------> check association between Face of Mesh and Face of Body
            mFace = outMesh->get_mesh_face(i);
            ident = mFace->get_id();
            printf("From mesh Entity : Id of face %d =%d",i,ident);
            Dtk_TopologicalEntityPtr topo =TmpBody->GetPtr(ident);
            if ( topo == NULL )
                 printf("ERROR No entity Found ");
            else
            {
                 if ( topo->get_type_detk() != DTK_TYPE_FACE )
                      printf("ERROR isn't a Face entity !!!!!!");
                 else
                 {
                      Dtk_FacePtr face = Dtk_FacePtr::DtkDynamicCast(topo);  // you obtain the original face 
                      Dtk_InfoPtr inf = face->get_info();
                      if ( inf.IsNotNULL() )
                      {
                           int i1 = inf->GetId();
                           printf("Body face found %d name %s",i1,inf->GetName().c_str());
                           // you can access at color ( inf->GetColor() ) level .... and all fields of face
                      }
                 }
            }
            
   
   
            // Second Step ---------------->  Check Association between Edge of Face from mesh and Edge of Face from Body BOdy
            Dtk_tab<Dtk_tab<Dtk_PolylinePtr> > outBoundaries;
            tess_getBoundariesFromMeshFace(outMesh,mFace,outBoundaries);
            nb3=outBoundaries.size();
            printf("this face have %d loops",nb3);
            for ( k=0;k<nb3;k++)
            {
                 nb4=outBoundaries[k].size();
                 printf("loop %d have %d segments",k+1,nb4);
                 for ( l=0;l<nb4;l++)
                 {
                      Dtk_PolylinePtr pln;
                      pln = outBoundaries[k][l];
                      printf("segment %d have %d points",l+1,pln->GetNumPoints());
                      Dtk_Val dtk_val;
                      Dtk_InfoPtr info = pln->info();
                      if ( info.IsNotNULL() )
                      {
                           if ( info->FindAttribute("TOPO_ID_EDGE",dtk_val) == dtkNoError )
                           {
                                ident2 = dtk_val.GetInt();
                                topo =TmpBody->GetPtr(ident2);
                                if ( topo != NULL )
                                {
                                     if ( DTK_TYPE_EDGE != topo->get_type_detk() )
                                          printf ("corresp of edge ID %d type ERROR %ld",ident2, topo->get_type_detk());
                                     else
                                          printf ("corresp of edge ID %d type EDGE",ident2);
                                }
                                else
                                     printf ("TOPOLOGY info Incorrect %d",ident2);
                           }
                           else
                           {
                                printf "NO TOPOLOGY info attribut associated");
                           }
                      }
                      else
                      {
                           printf("NO TOPOLOGY info associated");
                      }
                 } // end of for nb4
            } // end of for nb3
       }  // end of for nbMeshFace
  }

After using one of the following tessellation methods :

• tess_FacesArrayToMesh(Dtk_tab<Dtk_FacePtr> &inTabFace,Dtk_MeshPtr &outMesh, Dtk_Int32 *outIsSolid) tess_FacesArrayToMesh()
  You can retrieve associations between Dtk_mesh_face and Dtk_FacePtr only with the following code :
  

  void check_id_faces(Dtk_MeshPtr &outMesh,Dtk_tab<Dtk_FacePtr> *MemoFace)
  {
       Dtk_Size_t i,nb,k,nb3,l,nb4,m;
       Dtk_ID ident,ident2;
       Dtk_FacePtr face;
       Dtk_InfoPtr info;
       Dtk_mesh_face *mFace;
       char ss[512];
       Dtk_Size_t nbMeshFaces = outMesh->get_nb_mesh_face();
   
       for(i = 0 ; i < nbMeshFaces ; ++i)
       {
            // First Step ------> check association between Face of Mesh and Face of Body
            mFace = outMesh->get_mesh_face(i);
            ident = mFace->get_id();
            printf("From mesh Entity : Id of face %d =%d",i,ident);
            
            if (( ident < 0 ) ||( ident > MemoFace->size() ))
                 printf("incorrect indice value !!!!!!");
            else
            {
                 Dtk_FacePtr face =MemoFace->at(ident);
                 Dtk_InfoPtr inf = face->get_info();
                 if ( inf.IsNotNULL() )
                 {
                      int i1 = inf->GetId();
                      printf("Body face found %d name %s",i1,inf->GetName().c_str());
                      // you can access at color ( inf->GetColor() ) level .... and all fields of face
                 }
            }
       }
  }

Sample to tessellate a Dtk_Body