+++ /dev/null
-OCAF Usage {#samples__ocaf}
-========
-
-## Getting Started
-
- At the beginning of your development, you first define an application class by inheriting from the Application abstract class.
- You only have to create and determine the resources of the application
- for specifying the format of your documents (you generally use the standard one) and their file extension.
-
- Then, you design the application data model by organizing attributes you choose among those provided with OCAF.
- You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient,
- you aggregate a User attribute identified as a reflection coefficient
- with a Real attribute containing the value of the coefficient (as such, you don't define a new class).
-
- If you need application specific data not provided with OCAF, for example,
- to incorporate a finite element model in the data structure,
- you define a new attribute class containing the mesh,
- and you include its persistent homologue in a new file format.
-
- Once you have implemented the commands which create and modify the data structure
- according to your specification, OCAF provides you, without any additional programming:
-
- * Persistent reference to any data, including geometric elements â€" several documents can be linked with such reference;
- * Document-View association;
- * Ready-to-use functions such as :
- * Undo-redo;
- * Save and open application data.
-
- Finally, you develop the application's graphical user interface using the toolkit of your choice, for example:
- * KDE Qt or GNOME GTK+ on Linux;
- * Microsoft Foundation Classes (MFC) on Windows Motif on Sun;
- * Other commercial products such as Ilog Views.
-
- You can also implement the user interface in the Java language using
- the Swing-based Java Application Desktop component (JAD) provided with OCAF.
-
-## An example of OCAF usage
-
-To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
-
-In the <i> Formats </i> method, add the format of the documents, which need to be read by the application and may have been built in other applications.
-
-For example:
-
-~~~~
- void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
- {
- Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
- }
-~~~~
-
-In the <i> ResourcesName</i> method, you only define the name of the resource file. This
-file contains several definitions for the saving and opening mechanisms associated
-with each format and calling of the plug-in file.
-
-~~~~
- Standard_CString myApplication::ResourcesName()
- {
- return Standard_CString ("Resources");
- }
-~~~~
-
-To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
-
-~~~~
- SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
- SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
-~~~~
-
-The plugin and the resource files of the application will be located in <i> myDirector</i>.
-The name of the plugin file must be <i>Plugin</i>.
-
-### Resource File
-
-The resource file describes the documents (type and extension) and
-the type of data that the application can manipulate
-by identifying the storage and retrieval drivers appropriate for this data.
-
-Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
-
-Five drivers are required to use all standard attributes provided within OCAF:
-
- * the schema driver (ad696002-5b34-11d1-b5ba-00a0c9064368)
- * the document storage driver (ad696000-5b34-11d1-b5ba-00a0c9064368)
- * the document retrieval driver (ad696001-5b34-11d1-b5ba-00a0c9064368)
- * the attribute storage driver (47b0b826-d931-11d1-b5da-00a0c9064368)
- * the attribute retrieval driver (47b0b827-d931-11d1-b5da-00a0c9064368)
-
-These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
-
-
-For example, this is a resource file, which declares a new model document OCAF-MyApplication:
-
-~~~~
-formatlist:OCAF-MyApplication
-OCAF-MyApplication.Description: MyApplication Document Version 1.0
-OCAF-MyApplication.FileExtension: sta
-OCAF-MyApplication.StoragePlugin: ad696000-5b34-11d1-b5ba-00a0c9064368
-OCAF-MyApplication.RetrievalPlugin: ad696001-5b34-11d1-b5ba-00a0c9064368
-OCAF-MyApplicationSchema: ad696002-5b34-11d1-b5ba-00a0c9064368
-OCAF-MyApplication.AttributeStoragePlugin: 47b0b826-d931-11d1-b5da-00a0c9064368
-OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c9064368
-~~~~
-
-### Plugin File
-
-The plugin file describes the list of required plug-ins to run the application and the
-libraries in which plug-ins are located.
-
-You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
-
-The syntax of each item is <i> Identification.Location Library_Name, </i> where:
-* Identification is GUID.
-* Location defines the location of the Identification (where its definition is found).
-* Library_Name is the name (and path to) the library, where the plug-in is located.
-
-For example, this is a Plugin file:
-
-~~~~
-a148e300-5740-11d1-a904-080036aaa103.Location: FWOSPlugin
-! base document drivers plugin
-ad696000-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
-ad696001-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
-ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
-47b0b826-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
-47b0b827-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
-~~~~
-
-## Implementation of Attribute Transformation in a HXX file
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-\#include <TDF_Attribute.hxx>
-
-\#include <gp_Ax3.hxx>
-\#include <gp_Pnt.hxx>
-\#include <gp_Vec.hxx>
-\#include <gp_Trsf.hxx>
-
-//! This attribute implements a transformation data container
-class MyPackage_Transformation : public TDF_Attribute
-{
-public:
- //!@ name Static methods
-
- //! The method returns a unique GUID of this attribute.
- //! By means of this GUID this attribute may be identified
- //! among other attributes attached to the same label.
- Standard_EXPORT static const Standard_GUID& GetID ();
-
- //! Finds or creates the attribute attached to <theLabel>.
- //! The found or created attribute is returned.
- Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
-
- //!@ name Methods for access to the attribute data
-
- //! The method returns the transformation.
- Standard_EXPORT gp_Trsf Get () const;
-
- //!@ name Methods for setting the data of transformation
-
- //! The method defines a rotation type of transformation.
- Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle);
-
- //! The method defines a translation type of transformation.
- Standard_EXPORT void SetTranslation (const gp_Vec& theVector);
-
- //! The method defines a point mirror type of transformation (point symmetry).
- Standard_EXPORT void SetMirror (const gp_Pnt& thePoint);
-
- //! The method defines an axis mirror type of transformation (axial symmetry).
- Standard_EXPORT void SetMirror (const gp_Ax1& theAxis);
-
- //! The method defines a point mirror type of transformation (planar symmetry).
- Standard_EXPORT void SetMirror (const gp_Ax2& thePlane);
-
- //! The method defines a scale type of transformation.
- Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale);
-
- //! The method defines a complex type of transformation from one co-ordinate system to another.
- Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2);
-
- //!@ name Overridden methods from TDF_Attribute
-
- //! The method returns a unique GUID of the attribute.
- //! By means of this GUID this attribute may be identified among other attributes attached to the same label.
- Standard_EXPORT const Standard_GUID& ID () const;
-
- //! The method is called on Undo / Redo.
- //! It copies the content of theAttribute into this attribute (copies the fields).
- Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute);
-
- //! It creates a new instance of this attribute.
- //! It is called on Copy / Paste, Undo / Redo.
- Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const;
-
- //! The method is called on Copy / Paste.
- //! It copies the content of this attribute into theAttribute (copies the fields).
- Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable);
-
- //! Prints the content of this attribute into the stream.
- Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
-
- //!@ name Constructor
-
- //! The C++ constructor of this atribute class.
- //! Usually it is never called outside this class.
- Standard_EXPORT MyPackage_Transformation();
-
-private:
- gp_TrsfForm myType;
-
- // Axes (Ax1, Ax2, Ax3)
- gp_Ax1 myAx1;
- gp_Ax2 myAx2;
- gp_Ax3 myFirstAx3;
- gp_Ax3 mySecondAx3;
-
- // Scalar values
- Standard_Real myAngle;
- Standard_Real myScale;
-
- // Points
- gp_Pnt myFirstPoint;
- gp_Pnt mySecondPoint;
-};
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-## Implementation of Attribute Transformation in a CPP file
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-\#include <MyPackage_Transformation.hxx>
-
-//=======================================================================
-//function : GetID
-//purpose : The method returns a unique GUID of this attribute.
-// By means of this GUID this attribute may be identified
-// among other attributes attached to the same label.
-//=======================================================================
-const Standard_GUID& MyPackage_Transformation::GetID()
-{
- static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573");
- return ID;
-}
-
-//=======================================================================
-//function : Set
-//purpose : Finds or creates the attribute attached to <theLabel>.
-// The found or created attribute is returned.
-//=======================================================================
-Handle(MyPackage_Transformation) MyPackage_Transformation::Set(const TDF_Label& theLabel)
-{
- Handle(MyPackage_Transformation) T;
- if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T))
- {
- T = new MyPackage_Transformation();
- theLabel.AddAttribute(T);
- }
- return T;
-}
-
-//=======================================================================
-//function : Get
-//purpose : The method returns the transformation.
-//=======================================================================
-gp_Trsf MyPackage_Transformation::Get() const
-{
- gp_Trsf transformation;
- switch (myType)
- {
- case gp_Identity:
- {
- break;
- }
- case gp_Rotation:
- {
- transformation.SetRotation(myAx1, myAngle);
- break;
- }
- case gp_Translation:
- {
- transformation.SetTranslation(myFirstPoint, mySecondPoint);
- break;
- }
- case gp_PntMirror:
- {
- transformation.SetMirror(myFirstPoint);
- break;
- }
- case gp_Ax1Mirror:
- {
- transformation.SetMirror(myAx1);
- break;
- }
- case gp_Ax2Mirror:
- {
- transformation.SetMirror(myAx2);
- break;
- }
- case gp_Scale:
- {
- transformation.SetScale(myFirstPoint, myScale);
- break;
- }
- case gp_CompoundTrsf:
- {
- transformation.SetTransformation(myFirstAx3, mySecondAx3);
- break;
- }
- case gp_Other:
- {
- break;
- }
- }
- return transformation;
-}
-
-//=======================================================================
-//function : SetRotation
-//purpose : The method defines a rotation type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetRotation(const gp_Ax1& theAxis, const Standard_Real theAngle)
-{
- Backup();
- myType = gp_Rotation;
- myAx1 = theAxis;
- myAngle = theAngle;
-}
-
-//=======================================================================
-//function : SetTranslation
-//purpose : The method defines a translation type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector)
-{
- Backup();
- myType = gp_Translation;
- myFirstPoint.SetCoord(0, 0, 0);
- mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z());
-}
-
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines a point mirror type of transformation
-// (point symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint)
-{
- Backup();
- myType = gp_PntMirror;
- myFirstPoint = thePoint;
-}
-
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines an axis mirror type of transformation
-// (axial symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis)
-{
- Backup();
- myType = gp_Ax1Mirror;
- myAx1 = theAxis;
-}
-
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines a point mirror type of transformation
-// (planar symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Ax2& thePlane)
-{
- Backup();
- myType = gp_Ax2Mirror;
- myAx2 = thePlane;
-}
-
-//=======================================================================
-//function : SetScale
-//purpose : The method defines a scale type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_Real theScale)
-{
- Backup();
- myType = gp_Scale;
- myFirstPoint = thePoint;
- myScale = theScale;
-}
-
-//=======================================================================
-//function : SetTransformation
-//purpose : The method defines a complex type of transformation
-// from one co-ordinate system to another.
-//=======================================================================
-void MyPackage_Transformation::SetTransformation(const gp_Ax3& theCoordinateSystem1,
- const gp_Ax3& theCoordinateSystem2)
-{
- Backup();
- myFirstAx3 = theCoordinateSystem1;
- mySecondAx3 = theCoordinateSystem2;
-}
-
-//=======================================================================
-//function : ID
-//purpose : The method returns a unique GUID of the attribute.
-// By means of this GUID this attribute may be identified
-// among other attributes attached to the same label.
-//=======================================================================
-const Standard_GUID& MyPackage_Transformation::ID() const
-{
- return GetID();
-}
-
-//=======================================================================
-//function : Restore
-//purpose : The method is called on Undo / Redo.
-// It copies the content of <theAttribute>
-// into this attribute (copies the fields).
-//=======================================================================
-void MyPackage_Transformation::Restore(const Handle(TDF_Attribute)& theAttribute)
-{
- Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
- myType = theTransformation->myType;
- myAx1 = theTransformation->myAx1;
- myAx2 = theTransformation->myAx2;
- myFirstAx3 = theTransformation->myFirstAx3;
- mySecondAx3 = theTransformation->mySecondAx3;
- myAngle = theTransformation->myAngle;
- myScale = theTransformation->myScale;
- myFirstPoint = theTransformation->myFirstPoint;
- mySecondPoint = theTransformation->mySecondPoint;
-}
-
-//=======================================================================
-//function : NewEmpty
-//purpose : It creates a new instance of this attribute.
-// It is called on Copy / Paste, Undo / Redo.
-//=======================================================================
-Handle(TDF_Attribute) MyPackage_Transformation::NewEmpty() const
-{
- return new MyPackage_Transformation();
-}
-
-//=======================================================================
-//function : Paste
-//purpose : The method is called on Copy / Paste.
-// It copies the content of this attribute into
-// <theAttribute> (copies the fields).
-//=======================================================================
-void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute,
- const Handle(TDF_RelocationTable)& ) const
-{
- Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
- theTransformation->myType = myType;
- theTransformation->myAx1 = myAx1;
- theTransformation->myAx2 = myAx2;
- theTransformation->myFirstAx3 = myFirstAx3;
- theTransformation->mySecondAx3 = mySecondAx3;
- theTransformation->myAngle = myAngle;
- theTransformation->myScale = myScale;
- theTransformation->myFirstPoint = myFirstPoint;
- theTransformation->mySecondPoint = mySecondPoint;
-}
-
-//=======================================================================
-//function : Dump
-//purpose : Prints the content of this attribute into the stream.
-//=======================================================================
-Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const
-{
- anOS = "Transformation: ";
- switch (myType)
- {
- case gp_Identity:
- {
- anOS = "gp_Identity";
- break;
- }
- case gp_Rotation:
- {
- anOS = "gp_Rotation";
- break;
- }
- case gp_Translation:
- {
- anOS = "gp_Translation";
- break;
- }
- case gp_PntMirror:
- {
- anOS = "gp_PntMirror";
- break;
- }
- case gp_Ax1Mirror:
- {
- anOS = "gp_Ax1Mirror";
- break;
- }
- case gp_Ax2Mirror:
- {
- anOS = "gp_Ax2Mirror";
- break;
- }
- case gp_Scale:
- {
- anOS = "gp_Scale";
- break;
- }
- case gp_CompoundTrsf:
- {
- anOS = "gp_CompoundTrsf";
- break;
- }
- case gp_Other:
- {
- anOS = "gp_Other";
- break;
- }
- }
- return anOS;
-}
-
-//=======================================================================
-//function : MyPackage_Transformation
-//purpose : A constructor.
-//=======================================================================
-MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){
-
-}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-## Implementation of typical actions with standard OCAF attributes.
-
-There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers).
-The method *Sample()* of each file is not dedicated for execution 'as is', it is rather a set of logical actions using some OCAF services.
-
-### TDataStd_Sample.cxx
-This sample contains templates for typical actions with the following standard OCAF attributes:
-- Starting with data framework;
-- TDataStd_Integer attribute management;
-- TDataStd_RealArray attribute management;
-- TDataStd_Comment attribute management;
-- TDataStd_Name attribute management;
-- TDataStd_UAttribute attribute management;
-- TDF_Reference attribute management;
-- TDataXtd_Point attribute management;
-- TDataXtd_Plane attribute management;
-- TDataXtd_Axis attribute management;
-- TDataXtd_Geometry attribute management;
-- TDataXtd_Constraint attribute management;
-- TDataStd_Directory attribute management;
-- TDataStd_TreeNode attribute management.
-
-### TDocStd_Sample.cxx
-This sample contains template for the following typical actions:
-- creating application;
-- creating the new document (document contains a framework);
-- retrieving the document from a label of its framework;
-- filling a document with data;
-- saving a document in the file;
-- closing a document;
-- opening the document stored in the file;
-- copying content of a document to another document with possibility to update the copy in the future.
-
-### TPrsStd_Sample.cxx
-This sample contains template for the following typical actions:
-- starting with data framework;
-- setting the TPrsStd_AISViewer in the framework;
-- initialization of aViewer;
-- finding TPrsStd_AISViewer attribute in the DataFramework;
-- getting AIS_InteractiveContext from TPrsStd_AISViewer;
-- adding driver to the map of drivers;
-- getting driver from the map of drivers;
-- setting TNaming_NamedShape to \<ShapeLabel\>;
-- setting the new TPrsStd_AISPresentation to \<ShapeLabel\>;
-- displaying;
-- erasing;
-- updating and displaying presentation of the attribute to be displayed;
-- setting a color to the displayed attribute;
-- getting transparency of the displayed attribute;
-- modify attribute;
-- updating presentation of the attribute in viewer.
-
-### TNaming_Sample.cxx
-This sample contains template for typical actions with OCAF Topological Naming services.
-The following scenario is used:
-- data framework initialization;
-- creating Box1 and pushing it as PRIMITIVE in DF;
-- creating Box2 and pushing it as PRIMITIVE in DF;
-- moving Box2 (applying a transformation);
-- pushing the selected edges of the top face of Box1 in DF;
-- creating a Fillet (using the selected edges) and pushing the result as a modification of Box1;
-- creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF;
-- recovering the result from DF.
-
Read more about @subpage occt__tutorial
-MFC
----------
+@tableofcontents
-Visual C++ programming samples containing 10 Visual C++ projects
-illustrating how to use a particular module or functionality.
+@section tutorials_and_samples_overview Qt OCCT Overview Samples
+
+The Qt application providing samples for basic usage of C++ API of various OCCT functionality.
+
+The samples are organized in several categories according to relevant module of OCCT:
+
+ * Geometry
+ * Topology,
+ * Triangulation
+ * DataExchange
+ * OCAF
+ * Viewer 2d
+ * Viewer 3d
+
+Each sample presents geometry view, C++ code fragment and sample output window.
+
+@figure{/samples/images/overview_overview_qt.png}
+
+**Qt Overview samples**
+
+1. Contents
+-----------------------
+
+The directory <i> samples/qt/Overview </i> contains the folders and files of the Qt Overview application:
+
+* Files **Overview.pro** and **Overview0.pro** are Qt project files.
+* File **genproj.bat** to denerate MS Visual Studio project.
+* File **msvc.bat** to run MS Visual Studio project.
+* File **make.sh** to build of the application on Linux.
+* Files **run.bat** and **run.sh** to runn the application.
+* Files **env.bat** and **custom.bat** are called from *genproj.bat*, *msvc.bat*, *run.bat*. File *custom.bat*
+should be changed by user to provide paths to QT directory and CasCade installation directory.
+* **src** and **res** directories provide source and resources files.
+
+The directory <i> samples/Overview/code </i> contains the source code of samples.
+
+2. How to build Qt Overview application
+---------------------------------
+
+* Edit custom.bat file. It is necessary to define following variables:
+** QTDIR path to where Qt is installed
+** CASROOT path to where Open CasCade binaries are installed.
+
+* Build the application:
+** On Windows:
+*** Generate project files with help of genproj.bat. For example:
+~~~~
+ > genproj.bat vc141 win64 Debug
+~~~~
+*** Launch MS Visual Studio. For example:
+~~~~
+ > msvc.bat vc141 win64 Debug
+~~~~
+*** Build the application using MS Visual Studio.
+** On Linux: Launch building of the application by make.sh script
+
+3. Running the application
+--------------------------
+* On Windows:
+~~~~
+ > run.bat vc141 win64 Debug
+~~~~
+
+* On Linux:
+~~~~
+ > run.sh
+ ~~~~
+
+4. How to use the Overview application:
+---------------------------------
+
+* To select a samples categogy use the *Category* menu.
+* To run concrete sample using the menu to the right of the category menu.
+* See on a souce code in the *Sample code* window. Сopy the code if needed.
+* See on a sample output in the *Output* window if it exist.
+* Zoom, pan and rotate a geometry in the mail window using the mouse.
+See hints how to use the mouse in down hints panel.
+
+@section tutorials_mfc MFC Interactive samples
+
+MFC sample located within "samples\mfc\standard" folder represents an interactive tutorial for learning
+ OCCT components. Each sub-sample is devoted to specific OCCT domain, provides a set of small actions
+ like creation of a point or a B-Spline surface, which is displayed in 3D Viewer and accompanied by a
+ code snippet.
The list of MFC samples:
* Geometry
+ shows creation of geometrical objects (points, curves, surfaces).
+
* Modeling
+ shows creation of topological objects (primitives, Boolean operations).
+
+ * Convert
+ shows conversion of primitive geometry (circle, cylinder, Bézier, revolution) into B-Spline geometry.
+
+ * Triangulation
+ shows usage of meshing algorithm on shapes.
+
* Viewer2d
+ shows displaying various 2D objects in the Viewer.
+
* Viewer3d
- * ImportExport
+ shows displaying 3D objects, configuring light sources, shading model, applying textures in the 3D Viewer, etc.
+
+ * Animation
+ shows an animated 3D object in 3D Viewer.
+
* Ocaf
- * Triangulation
+ shows various operations on OCAF document.
+
* HLR
- * Animation
- * Convert
+ shows usage of HLR algorithm.
+
@figure{/samples/images/samples_mvc.png}
-**Remarks:**
+@section tutorials_and_samples_draw_harness Draw Harness Samples
+
+Draw Harness includes a set of Samples written in Tcl language demonstrating usage of OCCT components. Source code of Tcl Scripts is directly accessible and provided with comments.
+
+Samples are arranged into several groups:
+
+ * Modeling shows creation of a shape.
+
+ * XDE shows filling in exploration of XDE document (with colors, assembly structure, etc.).
+
+ * Visualization shows various 3D Viewer capabilities (materials, shading models, markers, Ray-Tracing).
+
+ * Demos: various demonstrations.
+
+Draw Demo Scripts
+----------------------------
+
+ All demo scripts are provided with OCCT sources and locate in <i>CASROOT/samples/tcl</i>. To play around them please
+follow the steps below:
+
+1. Start DRAWEXE
+2. Type *cd ../..* to return to the root directory
+3. Type *cd samples/tcl* to reach the *DrawResources* directory
+4. Type *source \<demo_file\>* to run the demonstration file provided with Open CASCADE. The following demonstration
+files are available:
+ * <b>DataExchangeDemo.tcl</b>: demonstrates sample sequence of operations with writing and reading IGES file
+ * <b>ModelingDemo.tcl</b>: demonstrates creation of simple shape and displaying it in HLR mode
+ * <b>VisualizationDemo.tcl</b>: demonstrates use of 3d viewer
+ * <b>cad.tcl</b>: creates solid shape looking like abbreviation "CAD"
+ * <b>bottle.tcl</b>: creates bottle as in OCCT Tutorial
+ * <b>drill.tcl</b>: creates twist drill bit shape
+ * <b>cutter.tcl</b>: creates milling cutter shape
+ * <b>xde.tcl</b>: demonstrates creation of simple assembly in XDE
+ * <b>materials.tcl</b>: demonstrates visual properties of materials supported by 3d viewer
+ * <b>raytrace.tcl</b>: demonstrates use of ray tracing display in 3d viewer
+ * <b>dimensions.tcl</b>: demonstrates use of dimensions, clipping, and capping in 3d viewer
+ * ...
+
+Draw is a command interpreter based on TCL and a graphical system used for testing and demonstrating OCCT modeling libraries.
+
+Draw can be used interactively to create, display and modify objects such as curves, surfaces and topological shapes.
+
+@figure{/introduction/images/overview_draw.png}
+
+Scripts can be written to customize Draw and perform tests.
+New types of objects and new commands can be added using C++ programming language.
+
+Draw contains:
+
+ * A command interpreter based on TCL command language.
+ * A 2D an 3D graphic viewer with support of operations such as zoom, pan, rotation and full-screen views.
+ * An optional set of geometric commands to create and modify curves and surfaces and to use OCCT geometry algorithms.
+ * A set of topological commands to create and modify BRep shapes and to use OCCT topology algorithms.
+ * A set of graphic commands for view and display operations including Mesh Visualization Service.
+ * A set of Application framework commands for handling of files and attributes.
+ * A set of Data Exchange commands for translation of files from various formats (IGES,STEP) into OCCT shapes.
+ * A set of Shape Healing commands: check of overlapping edges, approximation of a shape to BSpline, etc.
+
+You can add new custom test harness commands to Draw in order to test
+or demonstrate a new functionality, which you are developing.
+
+Currently DRAW Test Harness is a single executable called *DRAWEXE*.
+
+Commands grouped in toolkits can be loaded at run-time thereby implementing dynamically loaded plug-ins.
+Thus you can work only with the commands that suit your needs adding
+the commands dynamically without leaving the Test Harness session.
+
+Declaration of available plug-ins is done through special resource file(s).
+The *pload* command loads the plug-in in accordance with
+the specified resource file and activates the commands implemented in the plug-in.
+
+The whole process of using the plug-in mechanism as well as the instructions for extending Test Harness is described in the @ref occt_user_guides__test_harness.
+
+Draw Test Harness provides an environment for OCCT automated testing system.
+Check its @ref occt_contribution__tests "Automated Testing System" for details.
+
+Remarks:
+
+* The DRAWEXE executable is delivered with the installation procedure on Windows platform only.
+* To start it, launch DRAWEXE executable from Open CASCADE Technology/Draw Test Harness item of the Start\\Programs menu.
- * MFC samples are available only on Windows platform;
- * To start a sample use Open CASCADE Technology\\Samples\\Mfc\\ item of the Start\\Programs menu;
- * Read carefully readme.txt to learn about launching and compilation options.
+Experimenting with Draw Test Harness
+------------------------------------
-See @subpage samples_mfc_standard "Readme" for details.
+ Running Draw
+------------
-Qt
----
+**On Linux:**
- OCCT includes several samples based on Qt application framework.
-These samples are available on all supported desktop platforms.
+* If OCCT was built by Code::Blocks use <i>$CASROOT/draw.sh</i> file to launch *DRAWEXE* executable.
-To start a sample on Windows use Open CASCADE Technology\\Samples\\Qt\\ item of the Start\\Programs menu.
+Draw[1]> prompt appears in the command window
- Import Export
--------------
+Type *pload ALL*
- Import Export programming sample contains 3D Viewer and Import / Export functionality.
+**On Windows:**
+
+Launch Draw executable from Open CASCADE Technology\\Test Harness\\Draw Test Harness
+item of the Start\\Programs menu or Use <i>$CASROOT\\draw.bat</i> file to launch *DRAWEXE* executable.
+
+Draw[1]> prompt appears in the command window
+
+Type pload ALL
+
+**Creating your first geometric objects**
+
+1. In the command window, type *axo* to create an axonometric view
+2. Type *box b -10 -10 -10 20 20 20* to create a cube *b* of size 20, parallel to the X Y Z axis and centered on the origin. The cube will be displayed in the axonometric view in wireframe mode.
+3. Type *fit* to fill the viewer with the cube
+4. Type *pcylinder c 2 30* to create a cylinder *c* of radius 2 and height 30. The cylinder will be displayed in addition to the cube
+
+**Manipulating the view**
+
+1. Type *clear* to erase the view
+2. Type *donly c* to display the cylinder only
+3. Type *donly b* to display the cube only
+4. Type *hlr hlr b* to display the cube in the hidden line removal mode
+
+**Running demonstration files**
+
+1. Type *cd ../..* to return to the root directory
+2. Type *cd samples/tcl* to reach the *DrawResources* directory
+3. Type *source \<demo_file\>* to run the demonstration file provided with Open CASCADE. The following demonstration files are available:
+ * DataExchangeDemo.tcl: demonstrates sample sequence of operations with writing and reading IGES file
+ * ModelingDemo.tcl: demonstrates creation of simple shape and displaying it in HLR mode
+ * VisualizationDemo.tcl: demonstrates use of 3d viewer
+ * cad.tcl: creates solid shape looking like abbreviation "CAD"
+ * bottle.tcl: creates bottle as in OCCT Tutorial
+ * drill.tcl: creates twist drill bit shape
+ * cutter.tcl: creates milling cutter shape
+ * xde.tcl: demonstrates creation of simple assembly in XDE
+ * materials.tcl: demonstrates visual properties of materials supported by 3d viewer
+ * raytrace.tcl: demonstrates use of ray tracing display in 3d viewer
+ * dimensions.tcl: demonstrates use of dimensions, clipping, and capping in 3d viewer
+
+**Getting Help**
+
+1. Type *help* to see all available commands
+2. Type *help \<command_name\>* to find out the arguments for a given command
+
+@section tutorial_3d_viewer_integration 3D Viewer integration
+
+@subsection tutorial_3d_viewer_qt_viewer_sample Qt/QWidget Viewer sample
+
+ Qt IESample sample demonstrates OCCT 3D Viewer integration into Qt/QWidget application as well as model import/export functionality from/to external file.
@figure{/samples/images/samples_qt.png}
- Tutorial
----------
+@subsection tutorial_3d_viewer_qt_viewer_sample_android Qt/QtQuick Viewer sample (Android)
-The Qt programming tutorial teaches how to use Open CASCADE Technology services to model a 3D object.
-The purpose of the tutorial is not to explain all OCCT classes but
-to help start thinking in terms of the Open CASCADE Technology.
+This sample demonstrates a simple way of using OCCT libraries in Android application written using Qt/Qml.
-This tutorial assumes that the user has experience in using and setting up C++.
-From the viewpoint of programming, Open CASCADE Technology is designed
-to enhance user's C++ tools with high performance modeling classes, methods and functions.
-The combination of these resources allows creating substantial applications.
+The connection between Qt/Qml and OCCT (C++) level is provided by proxy library, libAndroidQt.so, written in C++.
+The proxy library contains single C++ class AndroidQt encapsulating OCCT viewer and providing functionality to manipulate this viewer
+and to import OCCT shapes from supported format of CAD file (BREP).
-**See also:** @ref occt__tutorial "OCCT Tutorial"
+Requirements for building sample:
+* Java Development Kit 1.7 or higher
+* Qt 5.3 or higher
+* Android SDK from 2014.07.02 or newer
+* Android NDK r9d or newer
+* Apache Ant 1.9.4 or higher
+* OCCT compiled under Android platform and placed in directories:
+ * occt/libs/armeabi-v7a/\*.so and occt/inc/\*.hxx (libraries and include files of OCCT install)
+ * android/assets/opencascade/shared/Shaders/\* (Shaders folder of OCCT install: /share/opencascade/resources/Shaders)
+ * 3rdparty/include/freetype2/\*, 3rdparty/include/FreeImage.h and 3rdparty/libs/armeabi-v7a/libFreeImage.so and 3rdparty/libs/armeabi-v7a/libfreetype.so
-Overview
----------
-
-The Qt application providing samples for basic usage of C++ API of various OCCT functionality.
+It is also possible to to correct OCCT.pri file an get resources from another tree of directories.
-The samples are organized in several categories according to relevant module of OCCT:
-
- * Geometry
- * Topology,
- * Triangulation
- * DataExchange
- * OCAF
- * Viewer 2d
- * Viewer 3d
+When AndroidQt will be started, it may be helpful to have some default data files(BRep) on Device for opening in AndroidQt.
+Copy these files into "android\assets\opencascade\shared" and it will be installed to device during compilation procedure.
+
+Having prepared all these products, configure AndroidQt project for building sample:
+
+In QtCreator, open AndroidQt.pro project-file:
+~~~~
+ File -> Open file or Project...
+~~~~
+
+Specify Android configurations:
+~~~~
+Tools->Options->Android
+~~~~
+* In JDK location specify path to Java Development Kit
+* In Android SDK location specify path to Android SDK
+* In Android NDK location specify path to Android NDK
+(During this location definition, warning is possible and OK:
+ "Qt version for architecture mips is missing. To add the Qt version, select Options > Build & Run > Qt Versins.")
+* In Ant executable specify path to ant.bat file located in Apache Ant bin directory
+
+Make sure that "Android for armeabi-v7a" kit has been detected (present in the list).
+~~~~
+Tools->Options->Build & Run
+~~~~
+
+also or it can be checked or corrected in:
+~~~~
+Projects->Android for armeabi-v7a option should be checked
+~~~~
+
+Switch On device, connect it to PC and define it in Qt Creator:
+~~~~
+Projects->Manage Kits...->Devices->Device: Run on Android
+~~~~
+Check that "Current state" is "Ready to use" on this page.
+
+~~~~
+Projects->Build Settings->General: Shadow build is switched OFF
+~~~~
+
+Start configuration:
+
+~~~~
+Call Build -> Run qmake
+~~~~
+Check content of "Compile Output" view.
+
+In order to perform qmake correctly, for example if you have the following error:
+~~~~
+Running steps for project AndroidQt...
+Could not start process "<qt_dir>\android_armv7\bin\qmake.exe" <occt_dir>\samples\qt\AndroidQt\AndroidQt.pro -r -spec android-g++ "CONFIG+=debug" "CONFIG+=declarative_debug" "CONFIG+=qml_debug"
+Error while building/deploying project AndroidQt (kit: Android for armeabi-v7a (GCC 4.9, Qt 5.3.2))
+When executing step "qmake"
+~~~~
+
+~~~~
+Projects->Build Settings->General: switch OFF Shadow build
+Build->Build Project "Android Qt"
+Build->Run
+~~~~
+
+Dialog to "Select Android Device" is shown. Select Compatible Device, Ok.
+In case of any error, see log in "Application Output" view.
+
+After successful build the application can be deployed to device or emulator.
+
+@figure{/samples/images/samples_qml_android_occt.jpg}
+
+@subsection tutorial_3d_viewer_c_winform C# C++/CLI WinForms sample
+
+WinForms sample demonstrates OCCT 3D Viewer integration into C# application using WinForms GUI framework via C++/CLI layer.
+
+The connection between .Net and OCCT (C++) level is provided by proxy library
+**OCCProxy**, written in C++/CLI. The proxy library contains a single *ref* class
+encapsulating OCCT viewer and providing the functionality to manipulate this viewer
+and to import / export OCCT shapes from / to several supported CAD file formats (IGES, STEP, BREP).
+
+The sample implements two approaches to the development of a user interface with C#.
+Both applications provide the same functionality as the standard OCCT Import/Export sample.
+The first project is called *IE_WinForms* and uses Windows Forms for GUI.
+The second application is called *IE_WPF_WinForms* and uses Windows Presentation Foundation.
+
+Note a few important details:
+
+- OCCT template class *NCollection_Haft* is used to encapsulate C++ class into a field of *ref* class;
+
+- It is necessary to explicitly set the target platform for C# assemblies to *x86*
+ in project **Properties - Build** to work consistently on 64-bit systems with OCCT libraries built in 32-bit mode;
+
+- this sample demonstrates indirect method of wrapping C++ to C# using a manually
+ created proxy library. There is an alternative method of wrapping individual
+ OCCT classes to C# equivalents to make their full API available to a C# user
+ and to let the code be programmed on C# level similarly to C++ one. See the description
+ of **OCCT C# Wrapper** in **Advanced Samples and Tools** at
+ http://www.opencascade.org/support/products/advsamples
+
+- in WPF sample, **WinForms** control is used to encapsulate OCC viewer since WPF
+ does not provide the necessary interface to embed OpenGl view. Other possible
+ solution could be to render OpenGl scene in an off-screen buffer and to map it
+ to WPF control as an image. That approach would allow using all WPF features to
+ control the OCCT viewer.
+
+Run *msvc.bat* to start MS Visual Studio for building the sample.
+Note that project files are provided only for VS 2010, you can open them in
+newer versions of Visual Studio the using automatic converter.
+
+After conversion check option **Target framework** in the properties of C# projects
+(tab **Application**) to make sure that it corresponds to the version set in
+the properties of C++ projects (e.g. <b>.Net Framework 4.0</b> for VS 2010).
+
+Run *run_winforms.bat* or *run_wpf.bat* to launch the corresponding sample.
+
+Note that all batch scripts use the configuration defined in OCCT *custom.bat* file
+as default; you can provide arguments specifying VS version, bitness, and mode
+to override these settings, e.g.:
+
+ > msvc.bat vc10 win64 Debug
+
+@subsection tutorial_3d_viewer_c_wpf C# C++/CLI WPF sample
+
+WPF sample demonstrates OCCT 3D Viewer integration into C# application using WPF GUI framework via C++/CLI layer
+
+The connection between .Net, OCCT (C++) and DirectX level is provided by proxy libraries,
+**OCCProxy** and **D3DProxy**, written in C++/CLI. The proxy library **OCCProxy** contains a single
+*ref* class encapsulating OCCT viewer and providing the functionality to manipulate this viewer
+and to import / export OCCT shapes from / to several supported CAD file formats (IGES, STEP,
+BREP). The proxy library **D3DProxy** contains helper methods for rendering via DirectX.
+
+The user interface in this sample is based on Windows Presentation Foundation (WPF).
+It has the same functionality as the standard OCCT Import/Export sample. The project is
+called *IE_WPF_D3D*.
+
+Note a few important details:
+
+- to build this sample you should to download and install DirectX SDK
+ http://www.microsoft.com/en-us/download/details.aspx?id=6812
+
+- OCCT template class *NCollection_Haft* is used to encapsulate C++ class into a field of *ref* class;
+
+- It is necessary to explicitly set the target platform for C# assemblies to *x86*
+ in project **Properties - Build** to work consistently on 64-bit systems with OCCT libraries built in 32-bit mode;
+
+- this sample demonstrates indirect method of wrapping C++ to C# using a manually
+ created proxy library. There is an alternative method of wrapping individual
+ OCCT classes to C# equivalents to make their full API available to a C# user
+ and to let the code be programmed on C# level similarly to C++ one. See the description
+ of **OCCT C# Wrapper** in **Advanced Samples and Tools** at
+ http://www.opencascade.org/support/products/advsamples
+
+- in WPF sample, **WinForms** control is used to encapsulate OCC viewer since WPF
+ does not provide the necessary interface to embed OpenGl view. Other possible
+ solution could be to render OpenGl scene in an off-screen buffer and to map it
+ to WPF control as an image. That approach would allow using all WPF features to
+ control the OCCT viewer.
+
+Run *msvc.bat* to start MS Visual Studio for building the sample.
+Note that project files are provided only for VS 2010, you can open them in
+newer versions of Visual Studio using an automatic converter.
+
+After conversion check option **Target framework** in the properties of C# projects
+(tab **Application**) to make sure that it corresponds to the version set in
+the properties of C++ projects (e.g. <b>.Net Framework 4.0</b> for VS 2010).
+
+Run *run_wpf-D3D.bat* to launch the corresponding sample.
+
+Note that all batch scripts use the configuration defined in OCCT *custom.bat* file
+as default; you can provide arguments specifying VS version, bitness, and mode
+to override these settings, e.g.:
+
+ > msvc.bat vc10 win64 Debug
+
+ @figure{/samples/images/samples_c__ie.png}
+
+@subsection tutorial_3d_viewer_webgl WebGL Viewer sample (WebAssembly)
+
+ WebGL sample demonstrates OCCT 3D Viewer integration into Web (HTML5/JavaScript) application.
+
+ Sample consists of the Open CASCADE 3D Viewer with a button for opening a model in BREP format.
+The sample requires a WebGL 2.0 capable browser supporting WebAssembly 1.0 (Wasm).
+
+Installation and configuration:
+ 1. Install Emscripten SDK and activate minimal configuration (Python, Java and CLang) following *emsdk* documentation. Activate also MinGW when building sample on Windows host.
+ 2. Build (using *emsdk*) or download FreeType static library.
+ 3. Configure CMake for building Open CASCADE Technology (OCCT) static libraries (BUILD_LIBRARY_TYPE="Static").
+ For this, activate *emsdk* command prompt, configure CMake for building OCCT using cross-compilation toolchain, disable *BUILD_MODULE_Draw*.
+ 4. Perform building and installation steps.
+~~~~~
+ > ${EMSDK}/fastcomp/emscripten/cmake/Modules/Platform/Emscripten.cmake
+~~~~~
+ 5. Configure CMake for building this WebGL sample using *emsdk* with paths to OCCT and FreeType. Perform building and installation steps.
+ 6. Copy data/occ/Ball.brep from OCCT into "samples" folder within WebGL sample installation path.
+ 7. Navigate to installation folder and start web server from it; Python coming with *emsdk* can be used for this purpose:
+~~~~~
+ > python -m SimpleHTTPServer 8080
+~~~~~
+ 8. Open compatible browser and enter path taking into account your web server settings:
+~~~~~
+ > http://localhost:8080/occt-webgl-sample.html
+~~~~~
+
+@figure{/samples/images/sample_webgl.png}
+
+@subsection tutorial_3d_viewer_glfw GLFW sample
+
+GLFW sample demonstrates OCCT 3D Viewer integration into GLFW application.
+
+@subsection tutorial_3d_viewer_mfc MFC Viewer sample
+
+MFC Import/Export sample demonstrates OCCT 3D Viewer integration into MFC application as well as model import/export functionality from/to external file.
+
+1. Contents
+-----------------------
+
+The directory <i> samples/mfc/standard </i> contains the following packages and files:
+
+* Numbered packages: **01_Geometry**, **02_Modeling**, etc. provide projects and sources of samples;
+* Files **All-vc(number).sln** are auxiliary utility projects depending on all other sample
+projects. When such project is rebuilt, all samples and *mfcsample* library are also rebuilt.
+* **Common** directory provides common source and header files for samples and dynamic-link library *mfcsample.dll.*
+* **Data** directory stores data files.
+* **mfcsample** directory contains project for *mfcsample.dll* library providing basic functionality used by all OCC samples.
+* File **env.bat** is called from *msvc.bat.*
+
+
+2. Launching Open CASCADE Technology samples:
+---------------------------------
+
+To run the Open CASCADE Technology samples, use command:
+
+~~~~
+execute run.bat [vc10|vc11|vc12|vc14] [win32|win64] [Release|Debug] [SampleName]
+~~~~
+
+To run the **Animation** sample, use command:
+
+~~~~
+execute run.bat vc10 win64 Debug Animation
+~~~~
+
+
+3. Modifying and rebuilding samples:
+--------------------------------------------
+
+You can modify, compile and launch all sample projects in MS Visual C++ at once with command:
+
+~~~~
+execute msvc.bat [vc10|vc11|vc12|vc14] [win32|win64] [Release|Debug]
+~~~~
+
+To run all sample projects in MS Visual C++ at once, use command:
+
+~~~~
+execute msvc.bat vc10 win64 Debug
+~~~~
+
+Note: make sure that your *PATH* environment variable contains a directory, where *msdev.exe* is located.
+
+@subsection tutorial_3d_viewer_java Java/JNI Viewer sample (Android)
+
+JniViewer sample demonstrates OCCT 3D Viewer integration into Java+JNI application for Android (can be also used as a base for QtQuick-based applications for other platforms).
+
+The connection between Java and OCCT (C++) level is provided by proxy library, libTKJniSample.so, written in C++ with exported JNI methods of Java class OcctJniRenderer.
+The proxy library contains single C++ class OcctJni_Viewer encapsulating OCCT viewer and providing functionality to manipulate this viewer
+and to import OCCT shapes from several supported formats of CAD files (IGES, STEP, BREP).
+
+This sample demonstrates indirect method of wrapping C++ to Java using manually created proxy library.
+Alternative method is available, wrapping individual OCCT classes to Java equivalents so that their full API is available to Java user
+and the code can be programmed on Java level similarly to C++ one.
+See description of OCCT Java Wrapper in Advanced Samples and Tools on OCCT web site at
+https://www.opencascade.com/content/advanced-samples-and-tools
+
+Install Android Studio 4.0+ and install building tools (check Tools -> SDK Manager):
+- Android SDK (API level 21 or higher).
+- Android SDK build tools.
+- Android NDK r16 or higher (coming with CMake toolchain).
+ Using NDK r18 or newer will require changing ANDROID_STL in project settings.
+- CMake 3.10+.
+
+Specify this folder location in Android Studio for opening project.
+You might need re-entering Android SDK explicitly in File -> Project Structure -> SDK Location settings (SDK, NDK, JDK locations).
+
+This sample expects OCCT to be already build - please refer to appropriate CMake building instructions in OCCT documentation.
+The following variables should be added into file gradle.properties (see gradle.properties.template as template):
+- `OCCT_ROOT` - path to OCCT installation folder.
+- `FREETYPE_ROOT` - path to FreeType installation folder.
+
+FreeImage is optional and does not required for this sample, however you should include all extra libraries used for OCCT building
+and load the explicitly from Java code within OcctJniActivity::loadNatives() method, including toolkits from OCCT itself in proper order:
+~~~~
+ if (!loadLibVerbose ("TKernel", aLoaded, aFailed)
+ || !loadLibVerbose ("TKMath", aLoaded, aFailed)
+ || !loadLibVerbose ("TKG2d", aLoaded, aFailed)
+~~~~
+Note that C++ STL library is not part of Android system, and application must package this library as well as extra component ("gnustl_shared" by default - see also `ANDROID_STL`).
+
+After successful build via Build -> Rebuild Project, the application can be packaged to Android:
+- Deploy and run application on connected device or emulator directly from Android Studio using adb interface by menu items "Run" and "Debug". This would sign package with debug certificate.
+- Prepare signed end-user package using wizard Build -> Generate signed APK.
+
+@figure{/samples/images/samples_java_android_occt.jpg}
+
+@subsection tutorial_3d_viewer_ios UIKit Viewer sample (iOS)
+
+UIKitSample sample demonstrates OCCT 3D Viewer integration into UIKit application for iOS.
+
+UIKitSample consists of the Open CASCADE 3D Viewer which provides import of STEP files and toolbar with three buttons.
+
+The first and second buttons serve for import hardcoded STEP files. The third button displays "About" dialog.
+
+The viewer supports zoom, pan and rotate actions. The viewer supports selection of solids as well.
+
+Installation and configuration:
+ 1. Make sure you are running Mac OS version 10.12.1 or above and properly installed XCode version 8.1 or above.
+ 2. Install Open CASCADE Technology (OCCT) and build static libraries for desired device or/and simulator on your workstation.
+ 3. Build or download Freetype2 static library for desired device or/and simulator.
+ 4. Open UIKitSample in XCode.
+ 5. Select the UIKitSample project and add the OCCT static libraries and Freetype2 static library.
+ 6. Select the UIKitSample and go to the "Build Settings" tab. After go to the section "Search Paths" and in the field "Header Search Paths" specify a path to the OCCT inc folder. Next in the field "Library Search Paths" specify a path/paths to the OCCT static libraries and Freetype2 static library folders.
+ 7. Connect device and build sample for device or choose simulator as a target and build for simulator.
+ 8. Run sample.
+
+@figure{/samples/images/sample_ios_uikit.png}
+
+@section tutorials_and_samples_advanced Advanced samples
+
+@subsection tutorials_and_samples_advanced_ocaf Qt OCAF FuncDemo
+
+Demonstrates usage of an advanced function mechanism of OCAF.
+
+OCAF Usage
+------------
+
+## Getting Started
+
+ At the beginning of your development, you first define an application class by inheriting from the Application abstract class.
+ You only have to create and determine the resources of the application
+ for specifying the format of your documents (you generally use the standard one) and their file extension.
+
+ Then, you design the application data model by organizing attributes you choose among those provided with OCAF.
+ You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient,
+ you aggregate a User attribute identified as a reflection coefficient
+ with a Real attribute containing the value of the coefficient (as such, you don't define a new class).
+
+ If you need application specific data not provided with OCAF, for example,
+ to incorporate a finite element model in the data structure,
+ you define a new attribute class containing the mesh,
+ and you include its persistent homologue in a new file format.
+
+ Once you have implemented the commands which create and modify the data structure
+ according to your specification, OCAF provides you, without any additional programming:
+
+ * Persistent reference to any data, including geometric elements â€" several documents can be linked with such reference;
+ * Document-View association;
+ * Ready-to-use functions such as :
+ * Undo-redo;
+ * Save and open application data.
-Each sample presents geometry view, C++ code fragment and sample output window.
+ Finally, you develop the application's graphical user interface using the toolkit of your choice, for example:
+ * KDE Qt or GNOME GTK+ on Linux;
+ * Microsoft Foundation Classes (MFC) on Windows Motif on Sun;
+ * Other commercial products such as Ilog Views.
-@figure{/samples/images/sample_overview_qt.png}
+ You can also implement the user interface in the Java language using
+ the Swing-based Java Application Desktop component (JAD) provided with OCAF.
+
+## An example of OCAF usage
+
+To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
+
+In the <i> Formats </i> method, add the format of the documents, which need to be read by the application and may have been built in other applications.
+
+For example:
+
+~~~~
+ void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
+ {
+ Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
+ }
+~~~~
+
+In the <i> ResourcesName</i> method, you only define the name of the resource file. This
+file contains several definitions for the saving and opening mechanisms associated
+with each format and calling of the plug-in file.
+
+~~~~
+ Standard_CString myApplication::ResourcesName()
+ {
+ return Standard_CString ("Resources");
+ }
+~~~~
+
+To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
+
+~~~~
+ SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
+ SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
+~~~~
+
+The plugin and the resource files of the application will be located in <i> myDirector</i>.
+The name of the plugin file must be <i>Plugin</i>.
+
+### Resource File
+
+The resource file describes the documents (type and extension) and
+the type of data that the application can manipulate
+by identifying the storage and retrieval drivers appropriate for this data.
+
+Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
+
+Five drivers are required to use all standard attributes provided within OCAF:
+
+ * the schema driver (ad696002-5b34-11d1-b5ba-00a0c9064368)
+ * the document storage driver (ad696000-5b34-11d1-b5ba-00a0c9064368)
+ * the document retrieval driver (ad696001-5b34-11d1-b5ba-00a0c9064368)
+ * the attribute storage driver (47b0b826-d931-11d1-b5da-00a0c9064368)
+ * the attribute retrieval driver (47b0b827-d931-11d1-b5da-00a0c9064368)
+
+These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
+
+
+For example, this is a resource file, which declares a new model document OCAF-MyApplication:
+
+~~~~
+formatlist:OCAF-MyApplication
+OCAF-MyApplication.Description: MyApplication Document Version 1.0
+OCAF-MyApplication.FileExtension: sta
+OCAF-MyApplication.StoragePlugin: ad696000-5b34-11d1-b5ba-00a0c9064368
+OCAF-MyApplication.RetrievalPlugin: ad696001-5b34-11d1-b5ba-00a0c9064368
+OCAF-MyApplicationSchema: ad696002-5b34-11d1-b5ba-00a0c9064368
+OCAF-MyApplication.AttributeStoragePlugin: 47b0b826-d931-11d1-b5da-00a0c9064368
+OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c9064368
+~~~~
+
+### Plugin File
+
+The plugin file describes the list of required plug-ins to run the application and the
+libraries in which plug-ins are located.
+
+You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
+
+The syntax of each item is <i> Identification.Location Library_Name, </i> where:
+* Identification is GUID.
+* Location defines the location of the Identification (where its definition is found).
+* Library_Name is the name (and path to) the library, where the plug-in is located.
+
+For example, this is a Plugin file:
+
+~~~~
+a148e300-5740-11d1-a904-080036aaa103.Location: FWOSPlugin
+! base document drivers plugin
+ad696000-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
+ad696001-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
+ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
+47b0b826-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
+47b0b827-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
+~~~~
-See \subpage samples_qt_overview "Readme" for details.
+## Implementation of Attribute Transformation in a HXX file
-C#
----
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+\#include <TDF_Attribute.hxx>
-C# sample demonstrates integration of OCCT 3D Viewer and Import / Export functionality into .NET applications (using Windows Forms and WPF front ends).
+\#include <gp_Ax3.hxx>
+\#include <gp_Pnt.hxx>
+\#include <gp_Vec.hxx>
+\#include <gp_Trsf.hxx>
-@figure{/samples/images/samples_c__ie.png}
+//! This attribute implements a transformation data container
+class MyPackage_Transformation : public TDF_Attribute
+{
+public:
+ //!@ name Static methods
-Import:
+ //! The method returns a unique GUID of this attribute.
+ //! By means of this GUID this attribute may be identified
+ //! among other attributes attached to the same label.
+ Standard_EXPORT static const Standard_GUID& GetID ();
- * BRep
- * Iges
- * Step
+ //! Finds or creates the attribute attached to <theLabel>.
+ //! The found or created attribute is returned.
+ Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
-Export:
+ //!@ name Methods for access to the attribute data
+
+ //! The method returns the transformation.
+ Standard_EXPORT gp_Trsf Get () const;
- * Brep
- * Iges
- * Step
- * Stl
- * Vrml
+ //!@ name Methods for setting the data of transformation
-See @subpage samples_csharp_occt "C# sample Readme" for details.
+ //! The method defines a rotation type of transformation.
+ Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle);
-There is also another C# example with the same functionality, which demonstrates the integration of Direct3D Viewer into .NET applications using WPF front end.
+ //! The method defines a translation type of transformation.
+ Standard_EXPORT void SetTranslation (const gp_Vec& theVector);
-See @subpage samples_csharp_direct3d "Direct3D C# sample Readme" for details.
+ //! The method defines a point mirror type of transformation (point symmetry).
+ Standard_EXPORT void SetMirror (const gp_Pnt& thePoint);
-Android
----------
+ //! The method defines an axis mirror type of transformation (axial symmetry).
+ Standard_EXPORT void SetMirror (const gp_Ax1& theAxis);
-There are two samples are representing usage OCCT framework on Android mobile platform. They represent an OCCT-based 3D-viewer with CAD import support in formats BREP, STEP and IGES: jniviewer (java) and AndroidQt (qt+qml)
+ //! The method defines a point mirror type of transformation (planar symmetry).
+ Standard_EXPORT void SetMirror (const gp_Ax2& thePlane);
-jniviewer
-@figure{/samples/images/samples_java_android_occt.jpg}
-Java -- See @subpage samples_java_android_occt "Android Java sample Readme" for details.
+ //! The method defines a scale type of transformation.
+ Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale);
-AndroidQt
-@figure{/samples/images/samples_qml_android_occt.jpg}
-Qt -- See \subpage samples_qml_android_occt "Android Qt sample Readme" for details.
+ //! The method defines a complex type of transformation from one co-ordinate system to another.
+ Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2);
-iOS
----
+ //!@ name Overridden methods from TDF_Attribute
+
+ //! The method returns a unique GUID of the attribute.
+ //! By means of this GUID this attribute may be identified among other attributes attached to the same label.
+ Standard_EXPORT const Standard_GUID& ID () const;
-There is a sample demonstrating usage of OCCT on iOS with Apple UIKit framework.
+ //! The method is called on Undo / Redo.
+ //! It copies the content of theAttribute into this attribute (copies the fields).
+ Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute);
-@figure{/samples/images/sample_ios_uikit.png}
+ //! It creates a new instance of this attribute.
+ //! It is called on Copy / Paste, Undo / Redo.
+ Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const;
-See @subpage occt_samples_ios_uikit "iOS sample Readme" for details.
+ //! The method is called on Copy / Paste.
+ //! It copies the content of this attribute into theAttribute (copies the fields).
+ Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable);
-Web
----------
+ //! Prints the content of this attribute into the stream.
+ Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
-WebGL Viewer sample demonstrating usage of OCCT 3D Viewer in Web browser with Emscripten SDK can be found in `samples/webgl`.
+ //!@ name Constructor
-@figure{/samples/images/sample_webgl.png}
+ //! The C++ constructor of this atribute class.
+ //! Usually it is never called outside this class.
+ Standard_EXPORT MyPackage_Transformation();
+
+private:
+ gp_TrsfForm myType;
+
+ // Axes (Ax1, Ax2, Ax3)
+ gp_Ax1 myAx1;
+ gp_Ax2 myAx2;
+ gp_Ax3 myFirstAx3;
+ gp_Ax3 mySecondAx3;
+
+ // Scalar values
+ Standard_Real myAngle;
+ Standard_Real myScale;
+
+ // Points
+ gp_Pnt myFirstPoint;
+ gp_Pnt mySecondPoint;
+};
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Implementation of Attribute Transformation in a CPP file
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+\#include <MyPackage_Transformation.hxx>
+
+//=======================================================================
+//function : GetID
+//purpose : The method returns a unique GUID of this attribute.
+// By means of this GUID this attribute may be identified
+// among other attributes attached to the same label.
+//=======================================================================
+const Standard_GUID& MyPackage_Transformation::GetID()
+{
+ static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573");
+ return ID;
+}
+
+//=======================================================================
+//function : Set
+//purpose : Finds or creates the attribute attached to <theLabel>.
+// The found or created attribute is returned.
+//=======================================================================
+Handle(MyPackage_Transformation) MyPackage_Transformation::Set(const TDF_Label& theLabel)
+{
+ Handle(MyPackage_Transformation) T;
+ if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T))
+ {
+ T = new MyPackage_Transformation();
+ theLabel.AddAttribute(T);
+ }
+ return T;
+}
+
+//=======================================================================
+//function : Get
+//purpose : The method returns the transformation.
+//=======================================================================
+gp_Trsf MyPackage_Transformation::Get() const
+{
+ gp_Trsf transformation;
+ switch (myType)
+ {
+ case gp_Identity:
+ {
+ break;
+ }
+ case gp_Rotation:
+ {
+ transformation.SetRotation(myAx1, myAngle);
+ break;
+ }
+ case gp_Translation:
+ {
+ transformation.SetTranslation(myFirstPoint, mySecondPoint);
+ break;
+ }
+ case gp_PntMirror:
+ {
+ transformation.SetMirror(myFirstPoint);
+ break;
+ }
+ case gp_Ax1Mirror:
+ {
+ transformation.SetMirror(myAx1);
+ break;
+ }
+ case gp_Ax2Mirror:
+ {
+ transformation.SetMirror(myAx2);
+ break;
+ }
+ case gp_Scale:
+ {
+ transformation.SetScale(myFirstPoint, myScale);
+ break;
+ }
+ case gp_CompoundTrsf:
+ {
+ transformation.SetTransformation(myFirstAx3, mySecondAx3);
+ break;
+ }
+ case gp_Other:
+ {
+ break;
+ }
+ }
+ return transformation;
+}
+
+//=======================================================================
+//function : SetRotation
+//purpose : The method defines a rotation type of transformation.
+//=======================================================================
+void MyPackage_Transformation::SetRotation(const gp_Ax1& theAxis, const Standard_Real theAngle)
+{
+ Backup();
+ myType = gp_Rotation;
+ myAx1 = theAxis;
+ myAngle = theAngle;
+}
+
+//=======================================================================
+//function : SetTranslation
+//purpose : The method defines a translation type of transformation.
+//=======================================================================
+void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector)
+{
+ Backup();
+ myType = gp_Translation;
+ myFirstPoint.SetCoord(0, 0, 0);
+ mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z());
+}
+
+//=======================================================================
+//function : SetMirror
+//purpose : The method defines a point mirror type of transformation
+// (point symmetry).
+//=======================================================================
+void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint)
+{
+ Backup();
+ myType = gp_PntMirror;
+ myFirstPoint = thePoint;
+}
+
+//=======================================================================
+//function : SetMirror
+//purpose : The method defines an axis mirror type of transformation
+// (axial symmetry).
+//=======================================================================
+void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis)
+{
+ Backup();
+ myType = gp_Ax1Mirror;
+ myAx1 = theAxis;
+}
+
+//=======================================================================
+//function : SetMirror
+//purpose : The method defines a point mirror type of transformation
+// (planar symmetry).
+//=======================================================================
+void MyPackage_Transformation::SetMirror(const gp_Ax2& thePlane)
+{
+ Backup();
+ myType = gp_Ax2Mirror;
+ myAx2 = thePlane;
+}
+
+//=======================================================================
+//function : SetScale
+//purpose : The method defines a scale type of transformation.
+//=======================================================================
+void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_Real theScale)
+{
+ Backup();
+ myType = gp_Scale;
+ myFirstPoint = thePoint;
+ myScale = theScale;
+}
+
+//=======================================================================
+//function : SetTransformation
+//purpose : The method defines a complex type of transformation
+// from one co-ordinate system to another.
+//=======================================================================
+void MyPackage_Transformation::SetTransformation(const gp_Ax3& theCoordinateSystem1,
+ const gp_Ax3& theCoordinateSystem2)
+{
+ Backup();
+ myFirstAx3 = theCoordinateSystem1;
+ mySecondAx3 = theCoordinateSystem2;
+}
+
+//=======================================================================
+//function : ID
+//purpose : The method returns a unique GUID of the attribute.
+// By means of this GUID this attribute may be identified
+// among other attributes attached to the same label.
+//=======================================================================
+const Standard_GUID& MyPackage_Transformation::ID() const
+{
+ return GetID();
+}
+
+//=======================================================================
+//function : Restore
+//purpose : The method is called on Undo / Redo.
+// It copies the content of <theAttribute>
+// into this attribute (copies the fields).
+//=======================================================================
+void MyPackage_Transformation::Restore(const Handle(TDF_Attribute)& theAttribute)
+{
+ Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
+ myType = theTransformation->myType;
+ myAx1 = theTransformation->myAx1;
+ myAx2 = theTransformation->myAx2;
+ myFirstAx3 = theTransformation->myFirstAx3;
+ mySecondAx3 = theTransformation->mySecondAx3;
+ myAngle = theTransformation->myAngle;
+ myScale = theTransformation->myScale;
+ myFirstPoint = theTransformation->myFirstPoint;
+ mySecondPoint = theTransformation->mySecondPoint;
+}
+
+//=======================================================================
+//function : NewEmpty
+//purpose : It creates a new instance of this attribute.
+// It is called on Copy / Paste, Undo / Redo.
+//=======================================================================
+Handle(TDF_Attribute) MyPackage_Transformation::NewEmpty() const
+{
+ return new MyPackage_Transformation();
+}
-See @subpage occt_samples_webgl "WebGL sample Readme" for details.
+//=======================================================================
+//function : Paste
+//purpose : The method is called on Copy / Paste.
+// It copies the content of this attribute into
+// <theAttribute> (copies the fields).
+//=======================================================================
+void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute,
+ const Handle(TDF_RelocationTable)& ) const
+{
+ Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
+ theTransformation->myType = myType;
+ theTransformation->myAx1 = myAx1;
+ theTransformation->myAx2 = myAx2;
+ theTransformation->myFirstAx3 = myFirstAx3;
+ theTransformation->mySecondAx3 = mySecondAx3;
+ theTransformation->myAngle = myAngle;
+ theTransformation->myScale = myScale;
+ theTransformation->myFirstPoint = myFirstPoint;
+ theTransformation->mySecondPoint = mySecondPoint;
+}
-OCAF Usage Sample
-------------------
+//=======================================================================
+//function : Dump
+//purpose : Prints the content of this attribute into the stream.
+//=======================================================================
+Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const
+{
+ anOS = "Transformation: ";
+ switch (myType)
+ {
+ case gp_Identity:
+ {
+ anOS = "gp_Identity";
+ break;
+ }
+ case gp_Rotation:
+ {
+ anOS = "gp_Rotation";
+ break;
+ }
+ case gp_Translation:
+ {
+ anOS = "gp_Translation";
+ break;
+ }
+ case gp_PntMirror:
+ {
+ anOS = "gp_PntMirror";
+ break;
+ }
+ case gp_Ax1Mirror:
+ {
+ anOS = "gp_Ax1Mirror";
+ break;
+ }
+ case gp_Ax2Mirror:
+ {
+ anOS = "gp_Ax2Mirror";
+ break;
+ }
+ case gp_Scale:
+ {
+ anOS = "gp_Scale";
+ break;
+ }
+ case gp_CompoundTrsf:
+ {
+ anOS = "gp_CompoundTrsf";
+ break;
+ }
+ case gp_Other:
+ {
+ anOS = "gp_Other";
+ break;
+ }
+ }
+ return anOS;
+}
-The provided set of samples dedicates to get initial knowledge about typical actions with OCAF services. It may be
-useful for newcomers.
+//=======================================================================
+//function : MyPackage_Transformation
+//purpose : A constructor.
+//=======================================================================
+MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){
-Read more about @subpage samples__ocaf
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-OCAF Function Mechanism Usage
------------------------------
+## Implementation of typical actions with standard OCAF attributes.
-This simple example dedicates to the usage of "Function Mechanism" of OCCT Application Framework. It represents a "nail"
-composed by a cone and two cylinders of different radius and height.
+There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers).
+The method *Sample()* of each file is not dedicated for execution 'as is', it is rather a set of logical actions using some OCAF services.
+
+### TDataStd_Sample.cxx
+This sample contains templates for typical actions with the following standard OCAF attributes:
+- Starting with data framework;
+- TDataStd_Integer attribute management;
+- TDataStd_RealArray attribute management;
+- TDataStd_Comment attribute management;
+- TDataStd_Name attribute management;
+- TDataStd_UAttribute attribute management;
+- TDF_Reference attribute management;
+- TDataXtd_Point attribute management;
+- TDataXtd_Plane attribute management;
+- TDataXtd_Axis attribute management;
+- TDataXtd_Geometry attribute management;
+- TDataXtd_Constraint attribute management;
+- TDataStd_Directory attribute management;
+- TDataStd_TreeNode attribute management.
+
+### TDocStd_Sample.cxx
+This sample contains template for the following typical actions:
+- creating application;
+- creating the new document (document contains a framework);
+- retrieving the document from a label of its framework;
+- filling a document with data;
+- saving a document in the file;
+- closing a document;
+- opening the document stored in the file;
+- copying content of a document to another document with possibility to update the copy in the future.
-Read more about @subpage samples__ocaf_func
+### TPrsStd_Sample.cxx
+This sample contains template for the following typical actions:
+- starting with data framework;
+- setting the TPrsStd_AISViewer in the framework;
+- initialization of aViewer;
+- finding TPrsStd_AISViewer attribute in the DataFramework;
+- getting AIS_InteractiveContext from TPrsStd_AISViewer;
+- adding driver to the map of drivers;
+- getting driver from the map of drivers;
+- setting TNaming_NamedShape to \<ShapeLabel\>;
+- setting the new TPrsStd_AISPresentation to \<ShapeLabel\>;
+- displaying;
+- erasing;
+- updating and displaying presentation of the attribute to be displayed;
+- setting a color to the displayed attribute;
+- getting transparency of the displayed attribute;
+- modify attribute;
+- updating presentation of the attribute in viewer.
-Draw Demo Scripts
-------------------
+### TNaming_Sample.cxx
+This sample contains template for typical actions with OCAF Topological Naming services.
+The following scenario is used:
+- data framework initialization;
+- creating Box1 and pushing it as PRIMITIVE in DF;
+- creating Box2 and pushing it as PRIMITIVE in DF;
+- moving Box2 (applying a transformation);
+- pushing the selected edges of the top face of Box1 in DF;
+- creating a Fillet (using the selected edges) and pushing the result as a modification of Box1;
+- creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF;
+- recovering the result from DF.
+
+
+Function Mechanism Usage
+------------------------
+
+Let us describe the usage of the "Function Mechanism" of Open CASCADE Application Framework on a simple example.
+This example represents a "nail" composed by a cone and two cylinders of different radius and height:
+
+@image html ocaf_functionmechanism_wp_image003.png "A nail"
+@image latex ocaf_functionmechanism_wp_image003.png " A nail"
+
+ These three objects (a cone and two cylinders) are independent,
+ but the Function Mechanism makes them connected to each other and representing one object -- a nail.
+ The object "nail" has the following parameters:
+
+ * The position of the nail is defined by the apex point of the cone.
+ The cylinders are built on the cone and therefore they depend on the position of the cone.
+ In this way we define a dependency of the cylinders on the cone.
+ * The height of the nail is defined by the height of the cone.
+ Let’s consider that the long cylinder has 3 heights of the cone
+ and the header cylinder has a half of the height of the cone.
+ * The radius of the nail is defined by the radius of the cone.
+ The radius of the long cylinder coincides with this value.
+ Let’s consider that the header cylinder has one and a half radiuses of the cone.
+
+ So, the cylinders depend on the cone and the cone parameters define the size of the nail.
+
+ It means that re-positioning the cone (changing its apex point) moves the nail,
+ the change of the radius of the cone produces a thinner or thicker nail,
+ and the change of the height of the cone shortens or prolongates the nail.
+ It is suggested to examine the programming steps needed to create a 3D parametric model of the "nail".
+
+## Step1: Data Tree
+
+ The first step consists in model data allocation in the OCAF tree.
+ In other words, it is necessary to decide where to put the data.
+
+ In this case, the data can be organized into a simple tree
+ using references for definition of dependent parameters:
+
+* Nail
+ * Cone
+ + Position (x,y,z)
+ + Radius
+ + Height
+ * Cylinder (stem)
+ + Position = "Cone" position translated for "Cone" height along Z;
+ + Radius = "Cone" radius;
+ + Height = "Cone" height multiplied by 3;
+ * Cylinder (head)
+ + Position = "Long cylinder" position translated for "Long cylinder" height along Z;
+ + Radius = "Long cylinder" radius multiplied by 1.5;
+ + Height = "Cone" height divided by 2.
+
+ The "nail" object has three sub-leaves in the tree: the cone and two cylinders.
+
+ The cone object is independent.
+
+ The long cylinder representing a "stem" of the nail refers to the corresponding parameters
+ of the cone to define its own data (position, radius and height). It means that the long cylinder depends on the cone.
+
+ The parameters of the head cylinder may be expressed through the cone parameters
+ only or through the cone and the long cylinder parameters.
+ It is suggested to express the position and the radius of the head cylinder
+ through the position and the radius of the long cylinder, and the height
+ of the head cylinder through the height of the cone.
+ It means that the head cylinder depends on the cone and the long cylinder.
+
+## Step 2: Interfaces
+
+ The interfaces of the data model are responsible for dynamic creation
+ of the data tree of the represented at the previous step, data modification and deletion.
+
+ The interface called *INail* should contain the methods for creation
+ of the data tree for the nail, setting and getting of its parameters, computation, visualization and removal.
+
+### Creation of the nail
+
+ This method of the interface creates a data tree for the nail at a given leaf of OCAF data tree.
+
+ It creates three sub-leaves for the cone and two cylinders and allocates the necessary data (references at the
+sub-leaves of the long and the head cylinders).
+
+ It sets the default values of position, radius and height of the nail.
+
+ The nail has the following user parameters:
+ * The position -- coincides with the position of the cone
+ * The radius of the stem part of the nail -- coincides with the radius of the cone
+ * The height of the nail -- a sum of heights of the cone and both cylinders
+
+ The values of the position and the radius of the nail are defined for the cone object data.
+ The height of the cone is recomputed as 2 * heights of nail and divided by 9.
+
+### Computation
+
+ The Function Mechanism is responsible for re-computation of the nail.
+ It will be described in detail later in this document.
+
+ A data leaf consists of the reference to the location of the real data
+ and a real value defining a coefficient of multiplication of the referenced data.
+
+ For example, the height of the long cylinder is defined as a reference to the height of the cone
+ with coefficient 3. The data leaf of the height of the long cylinder
+ should contain two attributes: a reference to the height of cone and a real value equal to 3.
+
+### Visualization
+
+ The shape resulting of the nail function can be displayed using the standard OCAF visualization mechanism.
+
+### Removal of the nail
+
+To automatically erase the nail from the viewer and the data tree it is enough to clean the nail leaf from attributes.
+
+## Step 3: Functions
+
+ The nail is defined by four functions: the cone, the two cylinders and the nail function.
+ The function of the cone is independent. The functions of the cylinders depend on the cone function.
+ The nail function depends on the results of all functions:
+
+@image html ocaf_functionmechanism_wp_image005.png "A graph of dependencies between functions"
+@image latex ocaf_functionmechanism_wp_image005.png "A graph of dependencies between functions"
+
+ Computation of the model starts with the cone function, then the long cylinder,
+ after that the header cylinder and, finally, the result is generated by the nail function at the end of function chain.
+
+ The Function Mechanism of Open CASCADE Technology creates this graph of dependencies
+ and allows iterating it following the dependencies.
+ The only thing the Function Mechanism requires from its user
+ is the implementation of pure virtual methods of *TFunction_Driver*:
+
+ * <i>\::Arguments()</i> -- returns a list of arguments for the function
+ * <i>\::Results()</i> -- returns a list of results of the function
+
+ These methods give the Function Mechanism the information on the location of arguments
+ and results of the function and allow building a graph of functions.
+ The class *TFunction_Iterator* iterates the functions of the graph in the execution order.
+
+ The pure virtual method *TFunction_Driver::Execute()* calculating the function should be overridden.
+
+ The method <i>\::MustExecute()</i> calls the method <i>\::Arguments()</i> of the function driver
+ and ideally this information (knowledge of modification of arguments of the function) is enough
+ to make a decision whether the function should be executed or not. Therefore, this method usually shouldn’t be overridden.
+
+ The cone and cylinder functions differ only in geometrical construction algorithms.
+ Other parameters are the same (position, radius and height).
+
+ It means that it is possible to create a base class -- function driver for the three functions,
+ and two descendant classes producing: a cone or a cylinder.
+
+ For the base function driver the methods <i>\::Arguments()</i> and <i>\::Results()</i> will be overridden.
+ Two descendant function drivers responsible for creation of a cone and a cylinder will override only the method
+<i>\::Execute()</i>.
+
+ The method <i>\::Arguments()</i> of the function driver of the nail returns the results of the functions located under
+it in the tree of leaves. The method <i>\::Execute()</i> just collects the results of the functions and makes one
+ shape -- a nail.
+
+ This way the data model using the Function Mechanism is ready for usage. Do not forget to introduce the function
+drivers for a function driver table with the help of *TFunction_DriverTable* class.
+
+### Example 1: iteration and execution of functions.
+
+ This is an example of the code for iteration and execution of functions.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+
+ // The scope of functions is defined.
+ Handle(TFunction_Scope) scope = TFunction_Scope::Set( anyLabel );
+
+ // The information on modifications in the model is received.
+ TFunction_Logbook& log = scope-GetLogbook();
+
+ // The iterator is iInitialized by the scope of functions.
+ TFunction_Iterator iterator( anyLabel );
+ Iterator.SetUsageOfExecutionOrder( true );
+
+ // The function is iterated, its dependency is checked on the modified data and executed if necessary.
+ for (; iterator.more(); iterator.Next())
+ {
+ // The function iterator may return a list of current functions for execution.
+ // It might be useful for multi-threaded execution of functions.
+ const TDF_LabelList& currentFunctions = iterator.Current();
+
+ //The list of current functions is iterated.
+ TDF_ListIteratorOfLabelList currentterator( currentFucntions );
+ for (; currentIterator.More(); currentIterator.Next())
+ {
+ // An interface for the function is created.
+ TFunction_IFunction interface( currentIterator.Value() );
+
+ // The function driver is retrieved.
+ Handle(TFunction_Driver) driver = interface.GetDriver();
+
+ // The dependency of the function on the modified data is checked.
+ If (driver-MustExecute( log ))
+ {
+ // The function is executed.
+ int ret = driver-Execute( log );
+ if ( ret )
+ return false;
+ } // end if check on modification
+ } // end of iteration of current functions
+ } // end of iteration of functions.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Example 2: Cylinder function driver
+
+ This is an example of the code for a cylinder function driver. To make the things clearer, the methods
+<i>\::Arguments()</i> and <i>\::Results()</i> from the base class are also mentioned.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-A set of demo scripts demonsrates using OCCT functionality from DRAW. These scripts can be also considered as a
-tutorials on tcl usage within Draw.
+ // A virtual method ::Arguments() returns a list of arguments of the function.
+ CylinderDriver::Arguments( TDF_LabelList& args )
+ {
+ // The direct arguments, located at sub-leaves of the fucntion, are collected (see picture 2).
+ TDF_ChildIterator cIterator( Label(), false );
+ for (; cIterator.More(); cIterator.Next() )
+ {
+ // Direct argument.
+ TDF_Label sublabel = cIterator.Value();
+ Args.Append( sublabel );
-Read more about @subpage samples__draw_scripts
+ // The references to the external data are checked.
+ Handle(TDF_Reference) ref;
+ If ( sublabel.FindAttribute( TDF_Reference::GetID(), ref ) )
+ {
+ args.Append( ref-Get() );
+ }
+ }
+
+ // A virtual method ::Results() returns a list of result leaves.
+ CylinderDriver::Results( TDF_LabelList& res )
+ {
+ // The result is kept at the function label.
+ Res.Append( Label() );
+ }
+
+ // Execution of the function driver.
+ Int CylinderDriver::Execute( TFunction_Logbook& log )
+ {
+ // Position of the cylinder - position of the first function (cone)
+ //is elevated along Z for height values of all previous functions.
+ gp_Ax2 axes = …. // out of the scope of this guide.
+ // The radius value is retrieved.
+ // It is located at second child sub-leaf (see the picture 2).
+ TDF_Label radiusLabel = Label().FindChild( 2 );
+
+ // The multiplicator of the radius ()is retrieved.
+ Handle(TDataStd_Real) radiusValue;
+ radiusLabel.FindAttribute( TDataStd_Real::GetID(), radiusValue);
+
+ // The reference to the radius is retrieved.
+ Handle(TDF_Reference) refRadius;
+ RadiusLabel.FindAttribute( TDF_Reference::GetID(), refRadius );
+
+ // The radius value is calculated.
+ double radius = 0.0;
+
+ if ( refRadius.IsNull() )
+ {
+ radius = radiusValue-Get();
+ }
+ else
+ {
+ // The referenced radius value is retrieved.
+ Handle(TDataStd_Real) referencedRadiusValue;
+ RefRadius-Get().FindAttribute(TDataStd_Real::GetID() ,referencedRadiusValue );
+ radius = referencedRadiusValue-Get() * radiusValue-Get();
+ }
+
+ // The height value is retrieved.
+ double height = … // similar code to taking the radius value.
+
+ // The cylinder is created.
+ TopoDS_Shape cylinder = BRepPrimAPI_MakeCylinder(axes, radius, height);
+
+ // The result (cylinder) is set
+ TNaming_Builder builder( Label() );
+ Builder.Generated( cylinder );
+
+ // The modification of the result leaf is saved in the log.
+ log.SetImpacted( Label() );
+
+ return 0;
+ }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
projects / occt-copy.git / commitdiff
