FinalMesh Boolean 3D Overview

For sample usage please see test.cpp in the test project.

Prerequisite

Copy ivmodule.dll to your project. You may copy it to the bin folder of your application or folder with modules. This choice is up to you. For the 32-bit project use the 32-bit version, for the 64-bit project use the 64-bit version.

Include ivboolean.h and declare pointers to 3 functions: iv3dInit, iv3dDone, iv3dCreate. Where iv3dInit - initialization of 3d module, iv3dDone - destroying of 3d module. iv3dCreate - creation of boolean processor object.

  	  IV3DINIT iv3dInit=NULL;
	  IV3DDONE iv3dDone=NULL;
	  IVBOOLCREATEPROC iv3dCreate=NULL;
	  HINSTANCE ivModule=0;

These may be global variables or data members of any object, structure. Naming is not critical. Load and initialize .dll only once. You may execute 3d boolean operation many times from multiple threads.

Loading

This quite a simple implementation shows how the 3d boolean library may be loaded and initialized.

bool MyLoadLibrary()
{
	HINSTANCE hi=LoadLibraryExA("ivmodule.dll",NULL,LOAD_WITH_ALTERED_SEARCH_PATH);
	if(hi)
	{
		iv3dCreate=(IVBOOLCREATEPROC )GetProcAddress(hi,"ivCreateBoolean");
		iv3dInit=(IV3DINIT)GetProcAddress(hi,"iv3dInit");
		iv3dDone=(IV3DDONE)GetProcAddress(hi,"iv3dDone");
		ivModule=hi;
		if(iv3dCreate && iv3dInit && iv3dDone)
		{
			iv3dInit();
			return true;
		};
	}
	return false;
}

This function, loads .dll, locates 3 functions and in case if all functions were found, initialises 3d library. For more detailed information please see this page.

Boolean Operation

Firstly you need to create 3d boolean processor:

ivbool3d::Processor*proc=iv3dCreate();

It is safe to call it from any thread.

Source Data

Now you should define source objects - A and B. Each operand can be made from many objects. You should avoid self-intersections on your own. The source object is created with AddSource method. The parameter is a type of the operand. 0 - A, 1- B.

ivbool3d::Object*obj=proc->AddSource(0);//A channel

Points

Vertices (Points) are defined with function obj->SetPoints. Parameters are an array of points and number of points. Each point is made of 3 float (or double) components: x,y,z.

Normals are defined with function: obj->SetNormals. Parameters are an array of normals and number of normals. Each normal is 3 floating point values. Single precision.

UV Coordinates: obj->SetUV. Each component is made of two floating point values.

Vertices should be added before faces. UV and Normals are optional, but if you want to process them, you should provide separate UV and normal faces.

Faces

Firstly you should define number of faces with help of obj->SetNumFaces method.

Each face can have different number of points. In case of 3 it will be triangle, 4 - quad, etc. Polygons will be triangulated automatically. Each face is created with obj->NewFace method. Parameters are: number of points in face and pointer to array of indices. Method returns index of face. In case of no errors, index is incremented from 0 to numFaces-1.

Normal faces should be created with SetNormalFace method. First parameter is index of face, second indices to array of normals.

UV faces should be created with SetUVFace0 method. First parameter is index of face, second indices to array of UV coordinates. For second UV channel, use SetUVFace1, etc. All UV channes share same array of UV coordinates.

Material index may be set with SetMtlID method. First parameter is index of face, second - index of material. Meaning of material is not important for 3d boolean.

Execution

When source objects are set, call Process method.

First parameter is type of boolean operation: OR, AND, SUB, CUT, UNION and variations.

Second parameter is combinations of flags:

• REDUCE - Reduce number of triangles by combining small triangles into one face, improve mesh quality, etc. For customizing reduce operation please use SetValue method.
• DEBUG_LOG - output logging information into Output window of Visual Studio.
• POLYGONISE - restore polygons from triangles. Use SetValue with BV_POLY_* properties to customize polygionization process.
• For the full list of options see description of Boolean options.

Get Results

If the process was successful, you may call GetResult method and retrieve constructed object. This method returns an object and you should use its methods to retrieve points, normals, UV, faces.

• GetPoints - returns pointer to an internal array of points and number of points in the array.
• GetNormals - returns pointer to an internal array of normals and the number of items in the array.
• GetUV - returns pointer to an internal array of UV points and the number of items in the array.
• GetNumFaces - returns the number of faces.
• GetFace - returns information about the face. The information consists of: size of face, indices to points, normals, UV, holes, etc.

Next Boolean operation

After the first execution, you may destroy the 3d boolean processor by calling Destroy method, create a new boolean object via iv3dCreate. Or you may clear the boolean processor with call Reset method instead. This will prepare 3d boolean processor for the next operation. The second way may be a little bit faster.

Destroying

On done, call iv3dDone function and unload dll with FreeLibrary function.

Debugging

If you have problems with filling in source objects, you may save the current state to .fmesh file, load it into FinalMesh, and check. In order to do that, before calling Process, call dbgSetSaveFileName method with the name of .fmesh file. After this, during the execution of Process method, the file will be saved and ready for inspection.