############################################################################### # # # Overview of the structure of the 3m_xxx and 2d_xxx source files # # # ############################################################################### Author: Menno Rubingh Date : 2009 May - 2010 Mar TERMINOLOGY Mesh Bounded surface segment, consisting of one mathematical surface (plane, cylinder, cone, or torus) together with the contours that bound the surface. [Note: The term "mesh" is NOT used in the 3m* code and documentation in its meaning of a net of surface segments approximating a complex surface.] ICS Intersection Curve Segment. Bounded curve segment forming a part of the intersection between the surfaces of two input solids to a CSG operation. ------------------------------------------------------------------------------- *1 LISTING OF THE SOURCE FILES ------------------------------------------------------------------------------- The listing below is ordered so that higher files generally use (depend on) only the files below them. **1.1 The 3m_xxx files ~~~~~~~~~~~~~~~~ ======================== ================================================ FILENAME PURPOSE ======================== ================================================ 3m_drawOpenGL.cpp Drawing of C3Model to OpenGL. 3m_drawOpenGL.h ------------------------ ------------------------------------------------ 3m_fromCGeo.cpp Conversion of CGeoXxx to C3Model. ------------------------ ------------------------------------------------ 3m_test.cpp Test cases, and test command interpreter 3m_test.h ("model_ExecTestCmd()"). ======================== ================================================ 3m_CSG.cpp Implementation of CSG. 3m_CSG.h 3m_intersectMeshes.cpp 3m_intersectMeshes.h 3m_compareEdges.cpp 3m_compareEdges.h 3m_intersectEdges.cpp 3m_intersectEdges.h 3m_NI2S.cpp 3m_NI2S.h ======================== ================================================ 3m_model.cpp Class C3Model. Contains the whole 3D-model. 3m_model.h ------------------------ ------------------------------------------------ 3m_base.cpp Classes CM3Point, CM3Edge, CM3Mesh, CM3Solid 3m_base.h and their subclasses. These contain PARTS of the 3D-model. ======================== ================================================ 3m_dump.cpp Debug print functions used by all of the 3m_dump.h 3m_xxx sources. ------------------------ ------------------------------------------------ 3m_intersectLines.cpp Simple general-purpose functions to intersect 3m_intersectLines.h two straight lines in 3D. ------------------------ ------------------------------------------------ 3m_TessWrapper.cpp Tessellator wrapper, used only by CM3MeshPlane. 3m_TessWrapper.h ======================== ================================================ **1.2 The 2d_xxx files ~~~~~~~~~~~~~~~~ ======================== ================================================ FILENAME PURPOSE ======================== ================================================ 2d_gridTess.cpp 2D-tessellator used for tessellating the 2d_gridTess.h curved surfaces. 2d_tess.cpp 2d_tess.h 2d_ab.cpp 2d_ab.h ======================== ================================================ ------------------------------------------------------------------------------- *2 STRUCTURE ------------------------------------------------------------------------------- **2.0 Layer diagram of dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each block in the diagram uses the blocks that are adjacent to its lower border, and may often use also the blocks that are in turn adjacent to the lower border of THOSE blocks. A block does NOT use any of the blocks vertically above it, or horizontally to the left or right of it. +-----------------------------------------------------------------------+ | | | Application program | | | +---------------+---------------------------------+---------------------+ | | 3m_fromCGeo | 3m_test | | | | | | +---------------------------------+---------------------+ | | CSG module: | | | ,-----------+--------------------------------------. | | 3m_drawOpenGL | | 3m_CSG | 3m_intersectMeshes | | | | | | | | | | +-----------+------+-------------------+-----------+ | | | | 3m_compareEdges | 3m_intersectEdges | 3m_NI2S | | | | `------------------+-------------------+-----------' | +---------------+-------------------------------------------------------+ | | | 3m_model | | | +-----------------------------------------------------------------------+ | | | 3m_base | | | +---------+-----------+----------------+--------------------------------+ | | | | 2D Grid Tessellator module: | | | | | ,----------------------------. | | 3m_dump | 3m_ | 3m_TessWrapper | | 2d_gridTess | | | | intersect | | +----------------------------+ | | | Lines | | | 2d_tess | | | | | | +----------------------------+ | | | | | | 2d_ab | | | | | | `----------------------------' | +---------+-----------+----------------+--------------------------------+ The diagram shows that the complete set of 3m_xxx and 2d_xxx sources is structured in three layers: Layer 3 High-level modules: All 3m_xxx files above 3m_model and 3m_base Layer 2 Core data structures: 3m_model and 3m_base Layer 1 Subordinate modules: All source files below 3m_model and 3m_base **2.1 Layer 1: Subordinate modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 2d_xxx files together form a completely separate module, that is usable separately from the 3m_xxx source files. The 2d_xxx module implements a special kind of tessellator in 2D-space (called the "2D Grid Tessellator") used by the 3m_xxx sources for tessellating the curved surfaces in 3D (which are two-dimensional surfaces, parameterized by two parameters). Likewise, 3m_TessWrapper.cpp/.h is a separate module. It is used only by the class CM3MeshPlane, and encapsulates the tessellator used by CM3MeshPlane. "3m_TessWrapper.cpp" is implemented currently by calling the OpenGL tessellator (GLUtessellator); another tessellator (for example, 2d_tess) can be substituted for this by changing only "3m_tessWrapper.cpp". 3m_dump.cpp/.h is another separate, stand-alone module. It implements the debug dump functions called by the other 3m_xxx sources (printing things to the debug log file). Finally, the source files 3m_intersectLines.cpp/.h define two simple stand-alone general-purpose functions [v3_intersectLines() and v3_linesNearestPoints()] used for intersecting straight lines: These functions find the point(s) on these lines where the lines are nearest to each other. These functions called often throughout the 3m* code, even by "3m_base.cpp". **2.2 Layer 2: Core data structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The core of the 3m_xxx sources are the following ones, which define the central data structures: 3m_model.cpp -- Class C3Model 3m_model.h 3m_base.cpp -- Classes CM3Point, CM3Edge, CM3Mesh, CM3Solid 3m_base.h and their subclasses. All the 3m_xxx files in Layer 3 use these data structures. **2.3 Layer 3: High-level modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~ ***2.3.1 CSG --- The CSG module is internally composed of two separate sub-layers: CSG module: ,-----------+--------------------------------------. | 3m_CSG | 3m_intersectMeshes | TOP SUBLAYER | | | +-----------+------+-------------------+-----------+ | 3m_compareEdges | 3m_intersectEdges | 3m_NI2S | BOTTOM SUBLAYER `------------------+-------------------+-----------' TOP SUBLAYER The top sublayer of the CSG module contains the two modules 3m_CSG and 3m_intersectMeshes, described in slightly more detail right below. 3m_CSG uses only 3m_compareEdges from the bottom sublayer; 3m_intersectMeshes uses all three modules (3m_compareEdges, 3m_intersectEdges, and 3m_NI2S) in the bottom layer. The CSG module as a whole exports only two functions: "intersect_twoSolids()" implemented by 3m_intersectMeshes, and "csg_createCSGSolid()" implemented by 3m_CSG. For each CSG operation that an application program wants to perform on two CM3Solid objects, it must always call both of these functions. The functions exported by the bottom sublayer (3m_compareEdges, 3m_intersectEdges, and 3m_NI2S) are hidden to client code (like 3m_fromCGeo) that uses the CSG module. 3m_CSG.cpp 3m_CSG.h Defines: Function csg_createCSGSolid() Purpose: From the output data of 3m_intersectMeshes, finds the "topology" of the resulting CSG solid, and creates a CM3Solid instance for it. 3m_intersectMeshes.cpp 3m_intersectMeshes.h Defines: Function intersect_twoSolids() Purpose: Finds the set of intersection curve segments between the surfaces of two CM3Solid solids. BOTTOM SUBLAYER The bottom sublayer of the CSG module contains the three pairs of .cpp/.h files listed below. 3m_compareEdges.cpp 3m_compareEdges.h Defines: Function edge_contains_edge() Function edges_same() Purpose: Given two CM3Edge objects, examine whether the 3D curve segment represented by the one is a section (subset) of the 3D curve segment represented the other, or whether both CM3Edge objects represent exactly the same 3D curve segments. This is used in both 3m_CSG.cpp and 3m_intersectMeshes.cpp to detect whether an ICS (Intersection Curve Segment) is wholly or partly identical to an existing contour edge, which in turn is necessary, among other things, for handling special cases in which intersection curves exactly coincide with the part of the contours of the input meshes. 3m_intersectEdges.cpp 3m_intersectEdges.h Defines: Function intersect_twoEdges() Purpose: Finds the intersection points of two arbitrary CM3Edge curves. This is used in 3m_intersectMeshes for determining the bounds of the intersection curve segments (by intersecting the intersection curves between two surfaces with the contours of a "mesh"), in cases where the intersection curve is NOT a CM3EdgeNumCOnS numerical curve. 3m_NI2S.cpp (Name stands for "Numerical Intersection of 2 Surfaces") 3m_NI2S.h Defines: Function findNumIntersCrvs() Function mesh_edge_intersect() Purpose: Function findNumIntersCrvs() intersects two arbitrary meshes numerically, and returns a set of numerical intersection curves (CM3EdgeNumCOnS objects). This is used in 3m_intersectMeshes to intersect two complex meshes, where the intersection curve can not easily be computed analytically. [Note: Mesh+Mesh intersections that can be relatively easily computed analytically are coded out inside 3m_intersectMeshes.] Function mesh_edge_intersect() intersects a surface with a curve numerically, and returns a set of intersection points. This is used in 3m_intersectMeshes for determining the bounds of the intersection curve segments (by intersecting the intersection curves between two surfaces with the contours of a "mesh"), in cases where the intersection curve IS a CM3EdgeNumCOnS numerical curve. [Note: See the src code comments in 3m_intersectMeshes.cpp above the call to mesh_edge_intersect() for an explanation why the function "intersect_twoEdges()" from 3m_intersectEdges can not be used in this case.] Each of these three .cpp/.h pairs in the CSG sublayer forms a stand-alone module on its own. This holds especially for 3m_intersectEdges and 3m_NI2S: These use only 3m_dump and and the pure virtual class interfaces CM3Edge and CM3Mesh (can intersect all kinds of CM3Edge and/or CM3Mesh objects); they are fully stand-alone otherwise. 3m_compareEdges needs slightly more knowledge about the CM3Edge implementation classes (it has if-then-else logic depending on the CM3EdgeXxx subclass of the input objects passed as its arguments). ***2.3.2 3m_test ------- The module 3m_test.cpp/.h defines a number of hard-coded test cases, and also defines the test command interpreter "model_ExecTestCmd()". The purpose of these cases is test a number of things that reside at a lower (= more detailed) level than can be tested conveniently via reading .wcd or .WID files. These tests are mostly concerned with the internals of the CSG operations, i.e. their purpose is mostly the testing of the source files described in §[2.3.1] above: intersection of edges and meshes, and the topology analysis executed internally in "3m_CSG.cpp". The purpose of the test command interpreter "model_ExecTestCmd()" is to allow that test commands can be sent to the 3m_xxx modules by the user of an application program. (Intended only for application programs compiled in DEBUG mode.) The application program need only provide a means for the user to enter a test command (= one string), and then pass that string to a call of "model_ExecTestCmd()". ***2.3.3 3m_drawOpenGL ------------- 3m_drawOpenGL.cpp contains the routines to draw the 3D-model to OpenGL. These routines were deliberately separated from the rest of the sources, so that - Porting to other drawing platforms is made easier - Changing the way the C3Model data is drawn on OpenGL only requires local changes to one source file - The C3Model data and C3Model operations (e.g., CSG) can be used independently of graphical output. This seems useful when the C3Model software is used only for data conversion (e.g., STEP output). ***2.3.4 3m_fromCGeo ----------- 3m_fromCGeo.cpp defines the function model_fromCGeo(), which reads a std::vector of CGeoSolid objects, and converts this to a C3Model instance. The function model_fromCGeo() is the only item exported by the 3m_fromCGeo.cpp/.h module. ------------------------------------------------------------------------------- --------------------------------End-Of-File------------------------------------ -------------------------------------------------------------------------------