c32ef176cab9f7d1168c56fb44fadc0c13db0c11
[occt.git] / dox / introduction / introduction.md
1 ´╗┐Introduction {#mainpage}
2 ========
3
4 @tableofcontents
5
6 @htmlonly<center>@endhtmlonly 
7 @figure{/resources/occt_logo.png}
8 @htmlonly</center>@endhtmlonly
9
10 Welcome to Open CASCADE Technology (OCCT), a software development platform 
11 providing services for 3D surface and solid modeling, CAD data exchange, and 
12 visualization. Most of OCCT functionality is available in the form of C++ 
13 libraries. OCCT can be best applied in development of software dealing with 3D 
14 modeling (CAD), manufacturing / measuring (CAM) or numerical simulation (CAE).
15
16 @htmlonly<center>@endhtmlonly
17 https://www.opencascade.com
18 @figure{/resources/occ_logo.png}
19 @htmlonly</center>@endhtmlonly
20
21 @section intro_overview Overview
22
23 Open CASCADE Technology (OCCT) is an object-oriented C++ class library designed for rapid production of sophisticated domain-specific CAD/CAM/CAE applications. 
24
25 A typical application developed using OCCT deals with two or three-dimensional (2D or 3D) geometric modeling
26 in general-purpose or specialized Computer Aided Design (CAD) systems, manufacturing
27 or analysis applications, simulation applications, or even illustration tools. 
28
29 OCCT library is designed to be truly modular and extensible, providing C++ classes for:
30   * Basic data structures (geometric modeling, visualization, interactive selection and application specific services); 
31   * Modeling algorithms; 
32   * Working with mesh (faceted) data; 
33   * Data interoperability with neutral formats (IGES, STEP); 
34
35 The C++ classes and other types are grouped into packages. Packages are organized into toolkits (libraries), to which you can link your application. Finally, toolkits are grouped into seven modules.
36
37 This modular structure is illustrated in the diagram below.
38
39 @figure{/introduction/images/technical_overview_schema.png}
40
41 * @ref intro_overview_fclasses  "Foundation Classes" module underlies all other OCCT classes; 
42 * @ref intro_overview_moddata   "Modeling Data" module supplies data structures to represent 2D and 3D geometric primitives and their compositions into CAD models; 
43 * @ref intro_overview_modalgo   "Modeling Algorithms" module contains a vast range of geometrical and topological algorithms;
44   * @ref intro_overview_mesh    "Mesh" toolkit from "Modeling Algorithms" module implements tessellated representations of objects;
45 * @ref intro_overview_visu      "Visualization" module provides complex mechanisms for graphical data representation;
46 * @ref intro_overview_de        "Data Exchange" module inter-operates with popular data formats and relies on @ref intro_overview_heal "Shape Healing" to improve compatibility between CAD software of different vendors;
47 * @ref intro_overview_ocaf      "Application Framework" module offers ready-to-use solutions for handling application-specific data (user attributes) and commonly used functionality (save/restore, undo/redo, copy/paste, tracking CAD modifications, etc). 
48
49 In addition, @ref intro_overview_draw "Open CASCADE Test Harness", also called Draw, provides an entry point to the library and can be used as a testing tool for its modules.
50
51 @subsection intro_overview_fclasses Foundation Classes
52
53 **Foundation Classes** module contains data structures and services used by higher-level Open CASCADE Technology classes:
54
55   * Primitive types, such as Boolean, Character, Integer or Real;
56   * String classes that handle Unicode strings;
57   * Collection classes that handle statically or dynamically sized aggregates of data, such as arrays, lists, queues, sets and hash tables (data maps).
58   * Classes providing commonly used numerical algorithms and basic linear algebra calculations (addition, multiplication, transposition of vectors and matrices, solving linear systems etc).
59   * Fundamental types like color, date and time information;
60   * Primitive geometry types providing implementation of basic geometric and algebraic entities that define and manipulate elementary data structures. 
61   * Exception classes that describe situations, when the normal execution of program is abandoned;
62
63 This module also provides a variety of general-purpose services, such as:
64   * Safe handling of dynamically created objects, ensuring automatic deletion of unreferenced objects (smart pointers);
65   * Standard and specialized memory allocators;
66   * Extended run-time type information (RTTI) mechanism maintaining a full type hierarchy and providing means to iterate over it;
67   * Encapsulation of C++ streams;
68   * Basic interpreter of expressions facilitating the creation of customized scripting tools, generic definition of expressions, etc.;
69   * Tools for dealing with configuration resource files and customizable message files facilitating multi-language support in applications;
70   * Progress indication and user break interfaces, giving a possibility even for low-level algorithms to communicate with the user in a universal and convenient way;
71   * and many others...
72
73 See the details in @ref occt_user_guides__foundation_classes "Foundation Classes User's Guide"
74
75 @subsection intro_overview_moddata Modeling Data
76
77 **Modeling Data** supplies data structures to implement boundary representation (BRep) of objects in 3D.
78 In BRep the shape is represented as an aggregation of geometry within topology.
79 The geometry is understood as a mathematical description of a shape, e.g. as curves and surfaces (simple or canonical, Bezier, NURBS, etc).
80 The topology is a data structure binding geometrical objects together.
81
82 Geometry types and utilities provide geometric data structures and services for:
83  * Description of points, vectors, curves and surfaces:
84    * their positioning in 3D space using axis or coordinate systems, and
85    * their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
86  * Creation of parametric curves and surfaces by interpolation and approximation;
87  * Algorithms of direct construction; 
88  * Conversion of curves and surfaces to NURBS form;
89  * Computation of point coordinates on 2D and 3D curves; 
90  * Calculation of extrema between geometric objects. 
91   
92 Topology defines relationships between simple geometric entities.
93 A shape, which is a basic topological entity, can be divided into components (sub-shapes):
94  * Vertex -- a zero-dimensional shape corresponding to a point;
95  * Edge -- a shape corresponding to a curve and bounded by a vertex at each extremity;
96  * Wire -- a sequence of edges connected by their vertices;
97  * Face -- a part of a plane (in 2D) or a surface (in 3D) bounded by wires;
98  * Shell -- a collection of faces connected by edges of their wire boundaries;
99  * Solid -- a finite closed part of 3D space bounded by shells;
100  * Composite solid -- a collection of solids connected by faces of their shell boundaries;
101  * Compound -- a collection of shapes of arbitrary type.
102
103 Complex shapes can be defined as assemblies (compounds) of simpler entities.
104
105 See the details in @ref occt_user_guides__modeling_data "Modeling Data User's Guide"
106
107 3D geometric models can be stored in OCCT native BREP format.
108 See @ref specification__brep_format "BREP Format Description White Paper" for details on the format.
109
110 @subsection intro_overview_modalgo Modeling Algorithms
111
112 **Modeling Algorithms** module groups a wide range of topological and geometric algorithms used in geometric modeling.
113 Basically, there are two groups of algorithms in Open CASCADE Technology:
114  * High-level modeling routines used in the real design;
115  * Low-level mathematical support functions used as a groundwork for the modeling API.
116
117 Low-level *geometric tools* provide the algorithms, which:
118  * Calculate the intersection of two curves, surfaces, or a curve and a surface;
119  * Project points onto 2D and 3D curves, points onto surfaces and 3D curves onto surfaces;
120  * Construct lines and circles from constraints;
121  * Construct free-form curves and surfaces from constraints (interpolation, approximation, skinning, gap filling, etc).
122   
123 Low-level *topological tools* provide the algorithms, which:
124  * Tessellate shapes;
125  * Check correct definition of shapes;
126  * Determine the local and global properties of shapes (derivatives, mass-inertia properties, etc);
127  * Perform affine transformations;
128  * Find planes in which edges are located;
129  * Convert shapes to NURBS geometry;
130  * Sew connected topologies (shells and wires) from separate topological elements (faces and edges).
131
132 Top-level API provides the following functionality: 
133  * Construction of Primitives:
134    * Boxes;
135    * Prisms;
136    * Cylinders;
137    * Cones;
138    * Spheres;
139    * Toruses.
140  * Kinematic Modeling:
141    * Prisms -- linear sweeps;
142    * Revolutions -- rotational sweeps;
143    * Pipes -- general-form sweeps;
144    * Lofting.
145
146 @figure{/introduction/images/0001.png "Shapes containing pipes with variable radius produced by sweeping"}
147
148  * Boolean Operations, which allow creating new shapes from the combinations of source shapes. For two shapes *S1* and *S2*:
149    * *Common* contains all points that are in *S1* and *S2*;
150    * *Fuse* contains all points that are in *S1* or *S2*;
151    * *Cut* contains all points in that are in *S1* and not in *S2*.
152
153 See @ref specification__boolean_operations "Boolean Operations" User's Guide for detailed documentation.
154
155  * Algorithms for local modifications such as:
156    * Hollowing;
157    * Shelling;
158    * Creation of tapered shapes using draft angles;
159    * Algorithms to make fillets and chamfers on shape edges, including those with variable radius (chord).
160
161  * Algorithms for creation of mechanical features, i.e. depressions, protrusions, ribs and grooves or slots along planar or revolution surfaces.
162
163 @figure{/introduction/images/0004.png}
164  
165 See the details in @ref occt_user_guides__modeling_algos "Modeling Algorithms User's Guide".
166
167 @subsection intro_overview_mesh Mesh
168
169 **Mesh** toolkit provides the functionality to work with tessellated representations of objects in form of triangular facets. This toolkit contains:
170 - data structures to store surface mesh data associated to shapes and basic algorithms to handle them;
171 - data structures and algorithms to build triangular surface mesh from *BRep* objects (shapes);
172 - tools for displaying meshes with associated pre- and post-processor data (scalars or vectors).
173
174 Open CASCADE SAS also offers Advanced Mesh Products:
175 - <a href="https://www.opencascade.com/content/mesh-framework">Open CASCADE Mesh Framework (OMF)</a>
176 - <a href="https://www.opencascade.com/content/express-mesh">Express Mesh</a>
177
178 @figure{/introduction/images/0003.png}
179
180 @subsection intro_overview_visu Visualization
181
182 **Visualization** module provides ready-to-use algorithms to create graphic presentations from various objects: shapes, meshes, etc.
183
184 In Open CASCADE Technology visualization is based on the separation of CAD data and its graphical presentation.
185 The module also supports a fast and powerful interactive selection mechanism. 
186
187 Visualization module relies on the following key toolkits:
188 - *TKV3d* toolkit defines a high-level API called (Application Interactive Services* (AIS) for working with interactive objects.
189 - *TKService* toolkit defines a low-level API for managing and creating presentations from primitive arrays.
190   This toolkit defines an abstraction layer for defining an arbitrary graphic driver responsible for actual rendering.
191 - *TKOpenGl* toolkit implements the graphic driver using OpenGL and OpenGL ES libraries.
192
193 While low-level API operates with primitive arrays (triangles, lines, points), the higher level includes services for building presentations for B-Rep shapes (shaded and wireframe).
194 A comprehensive list of standard interactive objects includes topological shape, mesh presentation, various dimensions, manipulators and others.
195 It provides a solid basis for rapid application development, while flexible and extensible API allows development of highly customized application-specific presentations.
196
197 Here are a few examples of OCCT Visualization features:
198 * Camera-driven view projection and orientation.
199   Perspective, orthographic and stereographic projections are supported.
200 * Support of Common (diffuse/ambient/specular) and PBR metallic-roughness material models.
201 * Possibility to flexibly adjust appearance of dimensions in a 3D view.
202   The 3D text object represents a given text string as a true 3D object in the model space.
203 * Definition of clipping planes through the plane equation coefficients.
204   Ability to define visual attributes for cross-section at the level or individual clipping planes.
205   In the image below different parts of the rocket are clipped with different planes and hatched.
206 @figure{/introduction/images/0008.png, "Display of shape cross-section and dimensions"}
207
208 * Support of built-in and application-specific GLSL shaders.
209 @figure{/introduction/images/0013.png, "Fragment shader implementing custom clipping surface"}
210
211 * Optimization of rendering performance through the algorithms of:
212   * View frustum culling, which skips the presentation outside camera at the rendering stage;
213   * Back face culling, which reduces the rendered number of triangles and eliminates artifacts at shape boundaries.
214 * Real-time ray tracing technique using recursive Whitted's algorithm and Bounded Volume Hierarchy effective optimization structure.
215 @figure{introduction/images/0002.png, "Real time visualization by ray tracing method"}
216 @figure{introduction/images/0012.png, "Simulation of a glass cover"}
217
218 For more details, see @ref occt_user_guides__visualization "Visualization User's Guide".
219
220 The visualization of OCCT topological shapes by means of VTK library provided by VIS component is described in a separate @ref occt_user_guides__vis "VTK Integration Services" User's Guide.
221
222 @subsection intro_overview_de Data Exchange
223
224 **Data Exchange** allows developing OCCT-based applications that can interact with other CAD systems by writing and reading CAD models to and from external data.
225
226 @figure{/introduction/images/0014.png,"Shape imported from STEP"}
227
228 **Data Exchange** is organized in a modular way as a set of interfaces that comply with various CAD formats: IGES, STEP, STL, VRML, etc.
229 The interfaces allow software based on OCCT to exchange data with various CAD/PDM software packages, maintaining a good level of interoperability.
230 This module handles various problems of interoperability between CAD systems, caused by differences in model validity criteria and requirements to internal representation.
231
232 * **Standardized Data Exchange** interfaces allow querying and examining the input file, converting its contents to a CAD model and running validity checks on a fully translated shape.
233   The following formats are currently supported:
234   * @ref occt_user_guides__step "STEP" (AP203: Mechanical Design, this covers General 3D CAD; AP214: Automotive Design; AP242).
235   * @ref occt_iges_1 "IGES" (up to 5.3).
236   * **glTF** 2.0 reader and writer.
237   * **OBJ** mesh file reader.
238   * **VRML** converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language).
239   * **STL** converter translates Open CASCADE shapes to STL files.
240     STL (STtereoLithography) format is widely used for rapid prototyping (3D printing).
241 * @ref occt_user_guides__xde "Extended data exchange" (XDE) allows translating  additional attributes attached to geometric data (colors, layers, names, materials etc).
242 * <a href="https://www.opencascade.com/content/advanced-data-exchange-components">Advanced Data Exchange Components</a>
243   are available in addition to standard Data Exchange interfaces to support interoperability and data adaptation (also using @ref intro_overview_heal "Shape Healing") with CAD software using the following proprietary formats:
244         * <a href="https://www.opencascade.com/content/acis-sat-import-export">ACIS SAT</a>
245         * <a href="https://www.opencascade.com/content/parasolid-import">Parasolid</a>
246         * <a href="https://www.opencascade.com/content/dxf-import-export">DXF</a>
247         * <a href="https://www.opencascade.com/content/ifc-import">IFC</a>
248         * <a href="https://www.opencascade.com/content/jt-import-export">JT</a>
249
250 These components are based on the same architecture as interfaces with STEP and IGES.
251
252 @subsection intro_overview_heal Shape Healing
253
254 **Shape Healing** library provides algorithms to correct and adapt the geometry and topology of shapes imported to OCCT from other CAD systems. 
255
256 Shape Healing algorithms include, but are not limited to, the following operations:
257  * Analyze shape characteristics and, in particular, identify the shapes that do not comply with OCCT geometry and topology validity rules by analyzing geometrical objects and topology:
258    - check edge and wire consistency;
259    - check edge order in a wire;
260    - check the orientation of face boundaries;
261    - analyze shape tolerances;
262    - identify closed and open wires in a boundary.
263  * Fix incorrect or incomplete shapes:
264    - provide consistency between a 3D curve and its corresponding parametric curve;
265    - repair defective wires;
266    - fit the shapes to a user-defined tolerance value;
267    - fill gaps between patches and edges.
268  * Upgrade and change shape characteristics:
269    - reduce curve and surface degree;
270    - split shapes to obtain C1 continuity;
271    - convert any types of curves or surfaces to Bezier or B-Spline curves or surfaces and back;
272    - split closed surfaces and revolution surfaces.
273
274 Each sub-domain of Shape Healing has its own scope of functionality:
275
276 | Sub-domain | Description | Impact on the shape |
277 | :--- | :---- | :---- |
278 | Analysis | Explores shape properties, computes shape features, detects violation of OCCT requirements. | The shape itself is not modified. |
279 | Fixing  | Fixes the shape to meet the OCCT requirements. | The shape may change its original form: modification, removal or creation of sub-shapes, etc.) |
280 | Upgrade | Improves the shape to fit some particular algorithms. | The shape is replaced with a new one, but geometrically they are the same. |
281 | Customization | Modifies the shape representation to fit specific needs. | The shape is not modified, only the mathematical form of its internal representation is changed. |
282 | Processing | Mechanism of shape modification via a user-editable resource file. | |
283
284 For more details, refer to @ref occt_user_guides__shape_healing "Shape Healing User's guide".
285
286 @subsection intro_overview_ocaf Application Framework
287
288 **Open CASCADE Application Framework** (OCAF) handles Application Data basing on the Application/Document paradigm.
289 It uses an associativity engine to simplify the development of a CAD application thanks to the following ready-to-use features and services:
290
291 * Data attributes managing the application data, which can be organized according to the development needs; 
292 * Data storage and persistence (open/save); 
293 * Possibility to modify and recompute attributes in documents.
294   With OCAF it is easy to represent the history of modification and parametric dependencies within your model;
295 * Possibility to manage multiple documents;  
296 * Predefined attributes common to CAD/CAM/CAE applications (e.g. to store dimensions);
297 * Undo-Redo and Copy-Paste functions.
298
299 Since OCAF handles the application structure, the only development task is the creation of application-specific data and GUIs. 
300
301 OCAF differs from any other CAD framework in the organization of application data, as there the data structures are based on reference keys rather than on shapes.
302 In a model, such attributes as shape data, color and material are attached to an invariant structure, which is deeper than the shapes.
303 A shape object becomes the value of *Shape* attribute, in the same way as an integer number is the value of *Integer* attribute and a string is the value of *Name* attribute.
304
305 OCAF organizes and embeds these attributes in a document. OCAF documents, in their turn, are managed by an OCAF application.
306
307 For more details, see @ref occt_user_guides__ocaf "OCAF User's Guide". 
308
309 @subsection intro_overview_draw Draw Test Harness
310
311 **Test Harness** or **Draw** is a convenient testing tool for OCCT libraries.
312 It can be used to test and prototype various algorithms before building an entire application.
313 It includes:
314 - A command interpreter based on the TCL language;
315 - A number of 2D and 3D viewers;
316 - A set of predefined commands.
317
318 The viewers support operations such as zoom, pan, rotation and full-screen views.
319
320 The basic commands provide general-purpose services such as:
321 - Getting help;
322 - Evaluating a script from a file;
323 - Capturing commands in a file;
324 - Managing views;
325 - Displaying objects.
326
327 In addition, **Test Harness** provides commands to create and manipulate curves and surfaces (geometry) and shapes, access visualization services, work with OCAF documents, perform data exchange, etc.
328
329 You can add custom commands to test or demonstrate any new functionalities, which you develop.
330
331 For more details, see @ref occt_user_guides__test_harness "Draw Test Harness Manual".
332
333 @section intro_req Requirements
334
335 Open CASCADE Technology is designed to be highly portable and is known to work on wide range of platforms.
336 Current version is officially certified on Windows (x86-64), Linux (x86-64), OS X / macOS (x86-64, arm64), Android (arm64), and iOS (arm64) platforms.
337
338 The tables below describe the recommended software configurations for which OCCT is certified to work.
339
340 @subsection intro_req_cpp C++ Compiler / IDE
341
342 | OS        | Compiler |
343 | --------- | ----------- |
344 | Windows   | Microsoft Visual Studio: 2010 SP1, 2012 Update 4, 2013 Update 5, 2015 Update 3, 2017 <sup>1</sup>, 2019 <br>, LLVM (ClangCL), GCC 4.3+ (Mingw-w64)|
345 | Linux     | GNU gcc 4.3+ <br> LLVM CLang 3.6+ |
346 | OS X / macOS | XCode 6 or newer |
347 | Android   | NDK r12, GNU gcc 4.9 or newer |
348 | Web       | Emscripten SDK 1.39 or newer (CLang) |
349
350 1) VC++ 141 64-bit is used for regular testing and for building binary package of official release of OCCT on Windows.
351
352 @subsection intro_req_libs Third-party libraries and tools
353
354 The following third-party libraries and tools are not included in OCCT sources but are either required or can be optionally used for the indicated components of OCCT.
355 They are not needed if relevant component is not needed.
356
357 Note that pre-built packages of many of the listed libraries are available at
358 https://www.opencascade.com/content/3rd-party-components
359
360 | Component | Where to find | Used for | Required or optional |
361 | --------- | ------------- | -------- | -------------------- |
362 | CMake 2.8+ | https://cmake.org/ | Build from sources | Optional |
363 | Intel TBB 4.x or later | https://www.threadingbuildingblocks.org/ | All | Optional (advanced parallelization of algorithms) |
364 | OpenGL 3.3+, OpenGL ES 2.0+ | System | Visualization | Required |
365 | OpenVR 1.10+ | https://github.com/ValveSoftware/openvr | Visualization | Optional (VR support) |
366 | Direct3D 9 | Windows | Visualization | Optional (integration with GUI using Direct3D) |
367 | FreeType 2.4+ | https://www.freetype.org/download.html | Visualization | Optional (text rendering) |
368 | FreeImage 3.17+ | https://sourceforge.net/projects/freeimage/files | Visualization | Optional (support of common 2D graphic formats) |
369 | FFmpeg 3.1+ | https://www.ffmpeg.org/download.html | Visualization | Optional (video recording) |
370 | VTK 6.1+ | https://www.vtk.org/download/ | Visualization | Optional (VTK integration) |
371 | Flex 2.6.4+ and Bison 3.7.1+ | https://sourceforge.net/projects/winflexbison/ | Data Exchange | Optional (update of STEP and ExprIntrp parsers) |
372 | RapidJSON 1.1+ | https://rapidjson.org/ | Data Exchange | Optional (reading glTF files) |
373 | Tcl/Tk 8.6.3+ <br> or ActiveTcl 8.6 | https://www.tcl.tk/software/tcltk/download.html <br> https://www.activestate.com/activetcl/downloads | DRAW Test Harness | Required |
374 | Qt Desktop: Qt 4.8.6+ <br> Android: Qt 5.3.2+ | https://www.qt.io/download/ | Samples and demos | Optional (Qt samples) |
375 | Doxygen 1.8.5+ | https://www.doxygen.nl/download.html | Documentation | Required |
376 | Graphviz 2.38+ | https://graphviz.org/ | Documentation | Optional (dependency graphs) |
377
378 @subsection intro_req_hw Hardware
379
380 | Component | Requirement |
381 | --------- | ----------- |
382 | Minimum memory    | 512 MB, 1 GB recommended |
383 | Free disk space (complete installation) | 1,5 GB approx. |
384
385 On desktop, 3D viewer for optimal performance requires graphics processing unit (GPU) supporting OpenGL 3.3 or above. 
386 Ray tracing requires OpenGL 4.0+ or OpenGL 3.3+ with *GL_ARB_texture_buffer_object_rgb32* extension.
387 Textures within ray tracing will be available only when *GL_ARB_bindless_texture extension* is provided by driver.
388
389 On mobile platforms, OpenGL ES 2.0+ is required for 3D viewer (OpenGL ES 3.1+ is recommended).
390 Ray tracing requires OpenGL ES 3.2.
391 Some old hardware might be unable to execute complex GLSL programs (e.g. with high number of light sources, clipping planes).
392
393 OCCT 3D Viewer, in general, supports wide range of graphics hardware - from very old to new.
394 Therefore, if you observe some unexpected visual issues - first check for OpenGL driver update (or firmware update in case of mobile platforms);
395 but beware that driver update might also come with new bugs.
396 Don't forget to report these bugs to vendors.
397
398 @section intro_install Download and Installation
399
400 OCCT can be downloaded from https://www.opencascade.com/content/latest-release
401
402 In most cases you would want to rebuild OCCT from sources on your platform (OS, compiler) before
403 using it in your project, to ensure binary compatibility and appropriate configuration of the library.
404 See @ref build_upgrade for instructions on building OCCT from sources on supported platforms.
405
406 The following subsections describe how OCCT can be installed from ready-to-use packages on different platforms.
407
408 @subsection intro_install_windows Windows
409
410 On Windows Open CASCADE Technology with binaries precompiled by Visual C++ 2017 
411 can be installed using installation procedure available on official download page.
412
413 **Recommendation:**
414
415 If you have a previous version of OCCT installed on your station, 
416 and you do not plan to use it along with the new version, you might want to uninstall 
417 the previous version (using Control Panel, Add/Remove Programs) before 
418 the installation of this new version, to avoid possible problems 
419 (conflict of system variables, paths, etc).
420
421 Full OCCT installation with reference documentation requires 1.8 Gb on disk.
422
423 When the installation is complete, you will find the directories for 3rd party products 
424 (some might be absent in case of custom installation) and the main **OCCT** directory:
425
426 @figure{/introduction/images/overview_3rdparty.png}
427
428 The contents of the OCCT-7.4.0 directory (called further "OCCT root", or $CASROOT) are as follows:
429
430 @figure{/introduction/images/overview_installation.png, "The directory tree"}
431
432   * **adm**   This folder contains administration files, which allow rebuilding OCCT;
433   * **adm/cmake**  This folder contains files of CMake building procedure;
434   * **adm/msvc**  This folder contains Visual Studio projects for Visual C++ 2010, 2012, 2013, 2015, 2017 and 2019 which allow rebuilding OCCT under Windows platform in 32 and 64-bit mode;
435   * **adm/scripts** This folder contains auxiliary scripts for semi-automated building and packaging of OCCT for different platforms;
436   * **data**  This folder contains CAD files in different formats, which can be used to test the OCCT functionality;
437   * **doc**  This folder contains OCCT documentation in HTML and PDF format;
438   * **dox**  This folder contains sources of OCCT documentation in plain text (MarkDown) format;
439   * **inc**  This folder contains copies of all OCCT header files;
440   * **samples**  This folder contains sample applications.
441   * **src**  This folder contains OCCT source files. They are organized in folders, one per development unit;
442   * **tests**  This folder contains scripts for OCCT testing.
443   * **tools**  This folder contains sources of Inspector tool.
444   * **win64/vc10**  This folder contains executable and library files built in optimize mode for Windows platform by Visual C++  2010;
445
446 @subsection intro_install_linux Linux
447
448 OCCT is available as package "opencascade" in official repositories of many Linux distributions.
449
450 See https://repology.org/project/opencascade/versions for overview of available repositories.
451
452 @subsection intro_install_mac macOS
453
454 On macOS, OCCT is available in Homebrew (https://formulae.brew.sh/formula/opencascade)
455 and MacPorts (https://ports.macports.org/port/opencascade/summary) repositories.
456
457 @section intro_env Environment Variables
458
459 To run any Open CASCADE Technology application you need to set the environment variables.
460
461 ### On Windows
462
463 You can define the environment variables with env.bat script located in the 
464 $CASROOT folder. This script accepts two arguments to be used: 
465 the version of Visual Studio (vc10 -- vc142) and the architecture (win32 or win64).
466
467 The additional environment settings necessary for compiling OCCT libraries and samples 
468 by Microsoft Visual Studio can be set using script custom.bat located in the same folder. 
469 You might need to edit this script to correct the paths to third-party libraries 
470 if they are installed on your system in a non-default location.
471
472 Script msvc.bat can be used with the same arguments for immediate launch of Visual Studio for (re)compiling OCCT.
473
474 ### On Unix
475
476
477   If OCCT was built by Code::Blocks, you can define the environment variables with env_cbp.sh or custom_cbp.sh script.
478
479   If OCCT was built by Automake, you can define the environment variables with env_amk.sh or custom_amk.sh script.
480
481 The scripts are located in the OCCT root folder.
482  
483 ### Description of system variables:
484
485   * **CASROOT** is used to define the root directory of Open CASCADE Technology;
486   * **PATH** is required to define the path to OCCT binaries and 3rdparty folder;
487   * **LD_LIBRARY_PATH** is required to define the path to OCCT libraries (on UNIX platforms only; **DYLD_LIBRARY_PATH** variable in case of macOS);
488   * **MMGT_OPT** (optional) if set to 1, the memory manager performs optimizations as described below; if set to 2, 
489     Intel (R) TBB optimized memory manager is used; if 0 (default), every memory block is allocated 
490     in C memory heap directly (via malloc() and free() functions). 
491     In the latter case, all other options starting with *MMGT*, except MMGT_CLEAR, are ignored;
492   * **MMGT_CLEAR** (optional) if set to 1 (default), every allocated memory block is cleared by zeros; 
493     if set to 0, memory block is returned as it is;
494   * **MMGT_CELLSIZE** (optional) defines the maximal size of blocks allocated in large pools of memory. Default is 200;
495   * **MMGT_NBPAGES** (optional) defines the size of memory chunks allocated for small blocks in pages 
496     (operating-system dependent). Default is 10000;
497   * **MMGT_THRESHOLD** (optional) defines the maximal size of blocks that are recycled internally 
498     instead of being returned to the heap. Default is 40000;
499   * **MMGT_MMAP** (optional) when set to 1 (default), large memory blocks are allocated using 
500     memory mapping functions of the operating system; if set to 0, 
501     they will be allocated in the C heap by malloc();
502   * **CSF_LANGUAGE** (optional) defines default language of messages;
503   * **CSF_DEBUG** (optional, Windows only): if defined then a diagnostic message is displayed in case of an exception;
504   * **CSF_DEBUG_BOP** (optional): if defined then it should specify directory where diagnostic data on problems occurred in Boolean operations will be saved;
505   * **CSF_MDTVTexturesDirectory** defines the directory for available textures when using texture mapping;
506   * **CSF_ShadersDirectory** (optional) defines the directory for GLSL programs for Ray Tracing renderer (embedded resources are used when variable is undefined);
507   * **CSF_SHMessage** (optional) defines the path to the messages file for *ShapeHealing*;
508   * **CSF_XSMessage** (optional) defines the path to the messages file for **STEP** and **IGES** translators;
509   * **CSF_StandardDefaults**, **CSF_StandardLiteDefaults*, **CSF_XCAFDefaults**, and **CSF_PluginDefaults** define paths to directory where configuration files for OCAF persistence are located (required for open/save operations with OCAF documents);
510   * **CSF_IGESDefaults** and **CSF_STEPDefaults** (optional) define paths to directory where resource files of **IGES** and **STEP** translators are located;
511   * **CSF_XmlOcafResource** is required in order to set the path to **XSD** resources, which defines XML grammar.
512   * **CSF_MIGRATION_TYPES** is required in order to read documents that contain old data types, such as *TDataStd_Shape*;
513
514 @section intro_license License
515
516 Open CASCADE Technology and all materials, including this documentation, is 
517 Copyright (c) 1999-2020 by OPEN CASCADE S.A.S. All rights reserved.
518
519 Open CASCADE Technology is free software; you can redistribute it and / or modify it under the terms of the 
520 @ref license_lgpl_21 "GNU Lesser General Public License (LGPL) version 2.1", with additional @ref occt_lgpl_exception "exception".
521
522 Note that LGPL imposes some obligations on the application linked with Open CASCADE Technology.
523 If you wish to use OCCT in a proprietary application, please pay a special attention to address the requirements of LGPL section 6.
524 At minimum the following should be considered:
525 1. Add the notice visible to the users of your application clearly stating that Open CASCADE Technology is used in this application, and that they have rights in this regard according to LGPL. 
526    Such notice can be added in About dialog box (this is mandatory if this box contains copyright statements) or a similar place and/or in the documentation. 
527    The text of LGPL license should be accessible to the user.
528 2. Make the copy of OCCT sources used by the application available to its users, and if necessary provide instructions on how to build it in a way compatible with the application.
529 3. Ensure that the user actually can exercise the right to run your application with a modified version of OCCT. 
530    If the application is distributed in a form that does not allow the user to modify OCCT part (e.g. the application is linked to OCCT statically or is distributed via AppStore on iOS, GooglePlay on Android, Windows Store, etc.), 
531    the application should be provided separately in a modifiable form, with all materials needed for the user to be able to run the application with a modified version of OCCT.
532
533 If you want to use Open CASCADE Technology without being bound by LGPL requirements, 
534 please <a href="https://www.opencascade.com/contact">contact Open CASCADE company</a> for a commercial license.
535
536 Note that Open CASCADE Technology is provided on an "AS IS" basis, WITHOUT 
537 WARRANTY OF ANY KIND. The entire risk related to any use of the OCCT code and 
538 materials is on you. See the @ref occt_public_license "license" text for formal 
539 disclaimer.
540
541 @section intro_acknowledge Acknowledgments
542
543 The following parties are acknowledged for producing tools which are used within 
544 Open CASCADE Technology libraries or for release preparation.
545
546 You are hereby informed that all rights to the software listed below belong to its respective 
547 authors and such software may not be freely available and/or be free of charge for any kind 
548 of use or purpose. We strongly recommend that you carefully read the license of these products 
549 and, in case you need any further information, directly contact their authors.
550
551 **Qt** is a cross-platform application framework that is widely used for developing application software 
552 with graphical user interface (GUI). Qt is free and open source software distributed under 
553 the terms of the GNU Lesser General Public License. In OCCT Qt is used for programming samples. 
554 If you need further information on Qt, refer to Qt Homepage (https://www.qt.io/)
555
556 **Tcl** is a high-level programming language. Tk is a graphical user interface (GUI) toolkit, 
557 with buttons, menus, listboxes, scrollbars, and so on. Taken together Tcl and Tk provide a solution 
558 to develop cross-platform graphical user interfaces with a native look and feel. Tcl/Tk is under copyright by 
559 Scriptics Corp., Sun Microsystems, and other companies. However, Tcl/Tk is an open source, and 
560 the copyright allows you to use, modify, and redistribute Tcl/Tk for any purpose, without an 
561 explicit license agreement and without paying any license fees or royalties. 
562 To use Tcl/Tk, refer to the Licensing Terms (https://www.tcl.tk/software/tcltk/license.html).
563
564 **FreeType 2** is developed by Antoine Leca, David Turner, Werner Lemberg and others. 
565 It is a software font engine that is designed to be small, efficient, highly customizable and 
566 portable while capable of producing high-quality output (glyph images). This product 
567 can be used in graphic libraries, display servers, font conversion tools, 
568 text image generation tools, and many other products.
569 FreeType 2 is released under two open-source licenses: BSD-like FreeType License and the GPL (https://www.freetype.org/license.html).
570
571 **Intel(R) Threading Building Blocks (TBB)** offers a rich and complete approach to expressing parallelism in a C++ program. 
572 It is a library that helps you to take advantage of multi-core processor performance without having to be a threading expert. 
573 Threading Building Blocks is not just a threads-replacement library. It represents a higher-level, task-based parallelism that 
574 abstracts platform details and threading mechanisms for scalability and performance. 
575 TBB version 2017 is available under Apache 2.0 license, while older versions 
576 until 4.4 are available under GPLv2 license with the runtime exception (https://www.threadingbuildingblocks.org).
577
578 **OpenGL** is an industry standard API for 3D graphics used by OCCT for 
579 implementation of 3D viewer. OpenGL specification is developed by the
580 Khronos group, https://www.khronos.org/opengl/. OCCT code includes header 
581 file *glext.h* obtained from Khronos web site.
582
583 **OpenVR** is an API and runtime that allows access to VR hardware from multiple vendors
584 without requiring that applications have specific knowledge of the hardware they are targeting.
585 OpenVR is optionally used by OCCT for VR support.
586 OpenVR is released under BSD-like license (https://github.com/ValveSoftware/openvr/blob/master/LICENSE).
587
588 **VTK** -- The **Visualization Toolkit (VTK)** is an open-source, freely available software system for 3D computer graphics, image processing and visualization.
589 OCCT VIS component provides adaptation functionality for visualization of OCCT topological shapes by means of VTK library.
590 If you need further information on VTK, refer to VTK Homepage https://www.vtk.org/.
591
592 **Doxygen** developed by Dimitri van Heesch is open source documentation system for 
593 C++, C, Java, Objective-C, Python, IDL, PHP and C#. This product is used in Open CASCADE Technology 
594 for automatic creation of Technical Documentation from C++ header files. 
595 If you need further information on Doxygen, refer to https://www.stack.nl/~dimitri/doxygen/index.html.
596
597 **Graphviz** is open source graph visualization software developed by John Ellson, Emden Gansner, Yifan Hu and Arif Bilgin. 
598 Graph visualization is representiation of structured information as diagrams of abstract graphs and networks. 
599 This product is used together with Doxygen in Open CASCADE Technology for automatic creation of Technical Documentation 
600 (generation of dependency graphs). Current versions of Graphviz are licensed on an open source 
601 basis under The Eclipse Public License (EPL) (https://www.graphviz.org/license/).
602
603 **Inno Setup** is a free script-driven installation system created in CodeGear Delphi by Jordan Russell. 
604 In OCCT Inno Setup is used to create Installation Wizard on Windows. 
605 It is licensed under Inno Setup License (http://www.jrsoftware.org/files/is/license.txt).
606
607 **FreeImage** is an Open Source library supporting popular graphics image formats, such as PNG, BMP, JPEG, TIFF, 
608 and others used by multimedia applications. This library is developed by Herv├ę Drolon and Floris van den Berg. 
609 FreeImage is easy to use, fast, multithreading safe, compatible with all 32-bit or 64-bit versions of Windows, 
610 and cross-platform (works both with Linux and Mac OS X). FreeImage is optionally used by OCCT to work
611 with images, on conditions of the FreeImage Public License (FIPL) (https://freeimage.sourceforge.net/freeimage-license.txt).
612
613 **FFmpeg** is an Open Source framework supporting various image, video and audio codecs.
614 FFmpeg is optionally used by OCCT for video recording, on LGPL conditions (https://www.ffmpeg.org/legal.html).
615
616 **David M. Gay's floating point routines** (dtoa.c) are used for fast reading of floating point values from text strings.
617 These routines are available under MIT-like license (see https://www.netlib.org/fp/).
618
619 **Flex** is a generator of lexical analyzers (scanners), available under BSD license (https://github.com/westes/flex).
620
621 GNU **Bison** is a parser generator used (together with **Flex**) for implementation of reader of STEP file format and parser of expressions.
622 It is available under GNU GPL v3 license (https://www.gnu.org/software/bison/).
623
624 **Delabella** is an open-source, cross-platform implementation of the Newton Apple Wrapper algorithm producing 2D Delaunay triangulation. 
625 Delabella is used by BRepMesh as one of alternative 2D triangulation algorithms. 
626 Delabella is licensed under the MIT license (https://github.com/msokalski/delabella).
627
628 **CMake** is an open-source, cross-platform family of tools designed to build, test and package software.
629 CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice. 
630 OCCT uses CMake as a build system. CMake is available under BSD 3-Clause license. 
631 See more at https://cmake.org/
632
633 **Cotire** (compile time reducer) is a CMake module that speeds up the build process of CMake based build systems 
634 by fully automating techniques as precompiled header usage and single compilation unit builds for C and C++.
635 Cotire is included in OCCT repository and used optionally by OCCT CMake scripts to accelerate builds by use of precompiled headers.
636 Cotire is licensed under the MIT license (https://github.com/sakra/cotire/blob/master/license).
637
638 **MikTEX** is up-to-date implementation of TeX/LaTeX and related programs for Windows. It is used 
639 for generation of User and Developer Guides in PDF format. See https://miktex.org for information
640 on this tool.
641
642 **RapidJSON** is an Open Source JSON parser and generator for C++.
643 RapidJSON is optionally used by OCCT for reading glTF files (https://rapidjson.org/).
644
645 **DejaVu** fonts are a font family based on the Vera Fonts under a permissive license (MIT-like, https://dejavu-fonts.github.io/License.html).
646 DejaVu Sans (basic Latin sub-set) is used by OCCT as fallback font when no system font is available.
647
648 Adobe Systems, Inc. provides **Adobe Reader**, which can be used to view files in Portable Document Format (PDF). 
649
650 **CAS.CADE** and **Open CASCADE** are registered trademarks of OPEN CASCADE S.A.S.
651
652 **Linux** is a registered trademark of Linus Torvalds.
653
654 **Windows** is a registered trademark of Microsoft Corporation in the United States and other countries.
655
656 **Mac**, **OS X**, **macOS**, and the Mac logo are trademarks of Apple Inc., registered in the U.S. and other countries.
657
658 **Android** is a trademark of Google LLC.