3DCoat Core API introduction

The Core API is a powerful method to extend 3DCoat's functionality. You can automate the job or add principally new tools. This is not just the scripting, the code you write runs at full speed of compiled C++. We use Microsoft Visual Studio for the compiling. But the whole process is entirely transparent for you. You don't need to configure anything or manage complex project configurations. 3DCoat will lead you through the whole process with a simple wizard.

Quickstart.

The core API requires Visual Studio 2022 Community with the C++ features installed. If you have not installed the Visual Studio, 3DCoat will help to install it with correct options.
The start is quite easy. Just use Scripts->Create new Core API script

Choose the template and path for your project. Then 3DCoat will assist you in installing the Visual Studio if needed.
Each example is well documented and uses relatively simple syntax, so it is easy to understand from basic to complex.
There are several important notes you need to know:
1) Always start your project from one of the examples. Even if you want to make everything from scratch, use Scripts->Create new Core API script->Minimal c++ program as your starting point. Don't create the project manually!
2) Use Debugging; it is very convenient; all 3DCoat native data types are shown in a user-friendly interface.
3) Always follow the Visual Studio linter hints to write the correct code. Hover the data types and function names to access the documentation on-the-fly.

4) Don't read the full documentation. It is impossible to remember. Follow the Examples first. And then look at the documentation if you need some details.
5) Look the C++ syntax, but don't read the whole manual, take the basics first - https://beginnersbook.com/2017/08/c-plus-plus-tutorial-for-beginners/
6) Click on the item in the Script menu to execute. Use RMB click to get the useful set of commends - edit, build, rebuild. Yoy may also create distributive of your script to share with oher users.

API reference

Pay attention. The API uses the same set of classes as 3DCoat. For the uniform look of the code, some types referred to in this document were renamed. For example, coat::vec3 is the same as cVec3. Please, use notation like coat::vec3 instead of cVec3 for 3d vectors (and similar for other vectors and matrices).

General I/O: coat::io
Dialog management: coat::dialog
Mesh operations: coat::Mesh
Scene roots: coat::Scene
Scene element: coat::SceneElement
Volume management: coat::Volume
UI management: coat::ui
2D-vectors math: coat::vec2, look the cVec2 for details.
3D-vectors math: coat::vec3, look the cVec3 for details.
4D-vectors math: coat::vec4, look the cVec4 for details.
3D-matrix math: coat::mat3, look the cMat3 for details.
4D-matrix math: coat::mat4, look the cMat4 for details.
Symmetry management: coat::symm
array: coat::list, look the cList and 3DCoat arrays for details.
Class registration rules and principles: ClassEngine introduction
Vector operations: 3DCoat math/vectors operations
Primitives: Construct scene using primitives, coat::box, coat::sphere, coat::ellipse, coat::gear, coat::cylinder, coat::ngon, coat::tube, coat::spiral, coat::torus.

Edit, auto-complete, correct hints

3DCoat generates cmake Visual Studio project to simplify the coding. If the free Visual Studio Express 2022 installed, the project will open automatically after the Script->Create Core API script. Of course, you should select the CPP file in the Solution Explorer to edit the code. We generate the project only to be able to edit with auto-complete and see the correct hints in the editor. Anyway, you can use Build->Build All in the Visual Studio to check for the syntax errors.

Debugging

Use Visual Studio for the debugging. Use Debug->Attach to process, 3DCoatGL64.exe, then open your script in Visual Studio, and set the breakpoint. Attach:

Select process:

Set breakpoint:

As soon as the script is executed, the VS stops at the breakpoint. Ensure that there is the 3dcoat.natvis file in the project folder. In this case, all the native 3DCoat types are shown correctly.
!!! Pay attention that if you ended the debug session and want to change the source file, you need to activate Debug->Detach All, otherwise 3DCoat will not be able to compile the project because the .pdb file is locked by the Visual Studio. Detach, then change sources, then attach again, and run the project using the Scripts->click on the project filename.

Examples

Looking the The Core API examples is the best way to understand the API. Use Scripts->Create new Core API script to experiment with that examples.

minimal.cpp
The minimal c++ program

C++ and CoreAPI basics

HelloWorld.cpp
The simplest program - just show the Hello world!

Strings.cpp
 Simple strings manipulations

Arrays.cpp
 Very basic arrays operations

Logging.cpp
 Output to the log file, writing to the text file

ui_command.cpp
This example demonstrates how to click any item in UI

dialogs.cpp
This example demonstrates the power of the dialogs and UI. It describes how to register the elements into the UI.

SculptTree operations

square_volume.cpp
Iterate over the sculpt tree, show the basic stats - square, volume

Generate objects

meshes.cpp
Generate the voxel figure that consists of random spheres

meshes_surface_merge.cpp
Generate the figure that consists of multiple spheres merged into the single surface object without booleans

metaballs.cpp
The metaballs example

GeneratorExample.cpp
The basic generator example, just to demonstrate the principles of generators, look the TreesGenerator.cpp for the more sophisticated example.

TreesGenerator.cpp
The trees generator example

Construct scene using primitives

csg_voxels.cpp
This example generates the detail for the further 3D printing using the voxels. The CSG principles demonstrated.

csg_surface.cpp
This example generates the detail for the further 3D printing using the surface mode. The CSG principles demonstrated.

BrickWall.cpp
Generate the surface figure "brick wall" that consists of boxes

capsule.cpp
This example generates the surface figure that consists of capsule

ellipses.cpp
This example generates the surface figure that consists of ellipses

gear.cpp
This example generates the surface figure that consists of gear

HoneyComb.cpp
This example generates the surface figure that consists of honey combs (ngons)

OlympicRings.cpp
This example generates the surface figure "olimpic rings" that consists of toruses

RollingPin.cpp
This example generates the surface figure rolling pin that consists of cylinders

spheres.cpp
Generate the surface figure that consists of spheres

spiral.cpp
This example generates the surface figure that consists of spiral

tube.cpp
This example generates the surface figure that consists of tube

WindRose.cpp
Generate the surface figure "windrose" that consists of cones

HelloWorld3D.cpp
Generate the text primitive

cup.cpp
Generate the surface figure "glass"

DoorStop.cpp
This example generates the surface figure door stop that consists of half-sphere and cylinders

bolt_binary.cpp
This example generates the bolt composite (bolt head + thread stud)

bolt_rim.cpp
This example generates the bolt composite (rim head + round thread profile)

boltheads.cpp
This example generates the bolt heads (hexa,flat,lamb)

screw.cpp
This example generates the bolt composite (bolt head + thread stud)

thread.cpp
This example generates the surface figure that consists of thread

threadStud.cpp
This example generates the surface figure that consists of thread stud

washer.cpp
This example generates the washer primitives (flat,grover,quard)

nut.cpp
This example generates the nut primitive.

ffBlob.cpp
This example generates the freeform primitive (blob)

ffCube.cpp
This example generates the freeform primitive (cube)

ffCylinder.cpp
This example generates the freeform primitive (cylinder)

Construct scene using primitives

Dumbbell.cpp
This example generates the surface figure dumb-bell with usage of the debug mode

Logo3D.cpp
This example generates the surface consist of logo 3D picture

Export