dox/user_guides/voxels_wp/voxels_wp.md

   1 Voxel Package {#occt_voxels_wp}
   2 ========================
   3
   4 @tableofcontents
   5
   6 @section occt_voxels_wp_1 Introduction
   7
   8   A voxel is a sub-volume box with constant  scalar/vector value.
   9   The object in voxel representation is split into many  small sub-volumes (voxels)
  10   and its properties are distributed through voxels.
  11
  12   Voxels are used for analysis and visualization of  3D-dimensional distribution of data.
  13   Medicine (mainly, tomography),  computational physics (hydrodynamics, aerodynamics, nuclear physics)
  14   and many  other industries use voxels for 3D data visualization and analysis of physical  processes.
  15
  16   To produce a voxel representation the 3D space is split by equal intervals
  17   along the main orthogonal coordinate axes to obtain nx  x ny x nz voxels (small cubes):
  18
  19 @image html voxels_wp_image003.jpg "A cube of 3 X 3 X 3  = 9 voxels."
  20 @image latex voxels_wp_image003.jpg "A cube of 3 X 3 X 3  = 9 voxels."
  21
  22   The data are attached to each voxel and remain the same  within the voxel.
  23   It means that we obtain the 3D space with discrete data distribution.
  24
  25   The number of voxels used in a calculation can vary.
  26   An  average model contains several tens of millions of voxels.
  27   Such a great amount  of data requires special algorithms of computation,
  28   data containers keeping  data in memory and visualization tools.
  29
  30   Open CASCADE Technology provides several basic data containers for voxels
  31   with fast access to the data and optimal allocation of  data in memory.
  32
  33   Also, a special visualization toolkit allows visualizing voxels
  34   as colored or black/white points and cubes, displaying only the voxels
  35   visible from the user's point of view.
  36
  37 @image html voxels_wp_image004.jpg "A shape and its voxel representation"
  38 @image html voxels_wp_image005.jpg  "A shape and its voxel representation"
  39 @image latex voxels_wp_image004.jpg "A shape and its voxel representation"
  40 @image latex voxels_wp_image005.jpg "A shape and its voxel representation"
  41
  42 In these images a boundary representation is displayed to the  left.  In the center and to the right there are 3D discrete representations (or  3D discrete topology).  Any solid shape can be translated into a voxel  representation.
  43
  44 @section occt_voxels_wp_2 Data structure
  45
  46   The data structure to store the voxels data is a  special class which gives
  47   fast access to the data of each voxel and allocates the data in an optimal way in the memory of a computer.
  48
  49   Fast access to the data is provided by means of  bit-wise operators on the indices of internal arrays.
  50
  51   The optimal data allocation is reached through  division
  52   of the whole data set into data subsets and keeping only non-zero  pieces of data in memory.
  53
  54   A voxel can contain different data types,
  55   but  presently Open CASCADE Technology implements only several basic ones:
  56   * 1 bit or Boolean data type – a voxel contains a flag: 0 or 1  (false or true).
  57   * 4 bits or Color data type – a voxel contains a value occupying 4  bits.
  58   It is an integer in the range of 0 .. 15. The data can be divided into 16  subsets and displayed by Color-voxels.
  59   * 4 bytes or Float data type – a voxel contains a floating-point  data type.
  60
  61   In addition, the data structures provide methods for calculation of a center point
  62   by voxel indices and a reverse task – fast search  of a voxel by a point inside the cube of voxels.
  63
  64 @section occt_voxels_wp_3 Algorithms
  65
  66   There are two service classes implemented for data  structures of voxels:
  67
  68   * Boolean operations – provides simple boolean operations on cubes  of voxels (fuse and cut).
  69   * Voxelization – the conversion of a geometrical model into its voxel representation.
  70
  71 ### Boolean operations
  72
  73 Fusion and cutting of two cubes of voxels are performed the class *Voxel_BooleanOperations*.   The cubes should have the same size and be split into voxels in the same way.
  74 * <i>::Fuse()</i> summarizes the values of the corresponding  voxels and limits the result by the upper limit (if succeeded).
  75 * <i>::Cut()</i> subtracts the values of the corresponding  voxels and limits the result by zero.
  76
  77 ### Voxelization
  78
  79 A class *Voxel_Convert* converts a *TopoDS_Shape*   into one of the voxel data structures filling the  solid shape by non-zero values.
  80
  81 The algorithm of voxelization generates only 1-bit or  4-bit voxels.   Other data types may be obtained by conversion of voxels from one  type to another.
  82
  83 Voxelization of a shape is performed by means of computation of intersection points  between lines filling the volume and  triangulation of the shape.  The lines are parallel to main orthogonal axes and  can intersect the shape from different sides: along +X, +Y and/or +Z axes.
  84
  85 The algorithm can run in multi-threaded mode (the number  of threads is unlimited).   The user can see an integer value indicating the  progress of computation.
  86
  87 @section occt_voxels_wp_4 Visualization
  88
  89   Visualization of voxels is not a simple task due to a  great amount of data used for 3D analysis.
  90
  91   Open CASCADE Technology allows visualization of a cube of voxels in two modes:
  92   * Points – the centers of voxels as 3D points.
  93   * Boxes – the voxels as 3D cubes of adjustable size.
  94
  95   A degenerated mode displays only the points (boxes) visible
  96   from the point of view of the user for transformation operations (zoom, pan and  rotate).
  97
  98   To focus on a particular part of the model non-relevant voxels can be erased.
  99   The displayed region is defined by six co-ordinates along  X, Y and Z axes .
 100
 101   It is possible to display the voxels from a particular range of values (iso-volume):
 102
 103 @image html voxels_wp_image006.jpg  "Iso-volume of a shape"
 104 @image latex voxels_wp_image006.jpg  "Iso-volume of a shape"
 105
 106 The voxels are displayed by means of "direct drawing  in Open GL" technology or "user draw" technology.   Therefore, some visualization  files are compiled within Open CASCADE Technology, but the files of "direct  drawing" are compiled  by the end-user application.
 107
 108 It is necessary to include the files *Voxel_VisData.h*,  *VoxelClient_VisDrawer.h* and *VoxelClient_VisDrawer.cxx*   into the  visualization library of the application (containing all files of *OpenGl*  package) and call the method *Voxel_VisDrawer::Init()* from the  application before the visualization of voxels.
 109
 110 @section occt_voxels_wp_5 Demo-application
 111
 112   A demonstration application has been created to show  OCCT voxel models.
 113   This is a test demo application because it includes a set of  non-regression tests
 114   and other commands for testing the functionality  (accessible only through TEST pre-processor definition).
 115
 116   The *File* menu allows creation of canonical  shapes (box, cylinder, sphere, torus) or loading of shapes in BREP format:
 117
 118 @image html voxels_wp_image007.jpg "Demo-application. Creation or loading of a shape"
 119 @image latex voxels_wp_image007.jpg "Demo-application. Creation or loading of a shape"
 120
 121 The menu *Converter* voxelizes the shape.   Two  types of voxels can be obtained: 1-bit or 4-bit voxels.
 122   * 1-bit voxels are displayed in white color on black background.
 123   * 4-bit voxels use 16 colors filling the model in a special way for demonstrative purposes:
 124
 125 @image html voxels_wp_image008.jpg "Demo-application.  Voxelization"
 126 @image latex voxels_wp_image008.jpg "Demo-application.  Voxelization"
 127
 128   The converter uses two threads (two processors, if  available) to perform voxelization.
 129
 130   The menu *Visualization* offers two modes of  visualization: Points and Boxes,
 131   allows defining the size of points and boxes  (quadrangles),
 132   the minimum and the maximum displayed color, and the boundaries of the bounding box for displayed voxels:
 133
 134 @image html voxels_wp_image009.jpg "Demo-application.  Visualization"
 135 @image latex voxels_wp_image009.jpg "Demo-application.  Visualization"
 136
 137   The last menu, *Demo* contains a demo-command for  running waves of 4-bit voxels:
 138
 139 @image html voxels_wp_image010.jpg  "Demo-application.  Running waves"
 140 @image latex voxels_wp_image010.jpg  "Demo-application.  Running waves"
 141
 142 @section occt_voxels_wp_6 Future development
 143
 144 In the future OPEN CASCADE  plans to develop the platform of voxels in the following directions:
 145   * Data structure:
 146     * Extension of the list of basic data types.
 147     * Development of a deeper hierarchy of voxels (for example, octree  – division of a voxel into 8 sub-voxels).
 148     * Development of a doxel (4D voxels where the fourth co-ordinate is  the time, for example).
 149
 150   * Algorithms:
 151     * Conversion of a voxel model into a geometrical model (a reversed  operation to voxelization).
 152
 153   * Visualization:
 154     * Optimization of visualization (mainly, the speed of  visualization).
 155     * New shapes of voxel presentation in the 3D Viewer and new  approaches to visualization.
 156     * Selection of voxels.
 157