Name Date Size

..18-Aug.-20214 KiB

.github/H05-Sep.-20204 KiB

.gitignoreH A D16-Aug.-2021715

Changelog.mdH A D05-Sep.-2020354

clang-formatH A D05-Sep.-20201 KiB

cmake/H05-Sep.-20204 KiB

CMakeLists.txtH A D04-Aug.-202113 KiB

CPackConfig.cmakeH A D05-Sep.-2020779

Cura.protoH A D05-Sep.-20204 KiB

CuraEngine.icoH A D05-Sep.-2020361.4 KiB

CuraEngine.rcH A D05-Sep.-2020596

docker/H02-Apr.-20214 KiB

docs/H05-Sep.-20204 KiB

DoxyfileH A D05-Sep.-202098 KiB

JenkinsfileH A D05-Sep.-20202.3 KiB

libs/H05-Sep.-20204 KiB

LICENSEH A D05-Sep.-202033.7 KiB

meta/H05-Sep.-20204 KiB

README.mdH A D05-Sep.-20209.9 KiB

src/H20-Sep.-20214 KiB

tests/H13-Aug.-20214 KiB

README.md

1CuraEngine
2==========
3The CuraEngine is a C++ console application for 3D printing GCode generation. It has been made as a better and faster alternative to the old Skeinforge engine.
4
5The CuraEngine is pure C++ and uses Clipper from http://www.angusj.com/delphi/clipper.php
6Furthermore it depends on libArcus by Ultimaker, which can be found at http://github.com/Ultimaker/libArcus
7
8This is just a console application for GCode generation. For a full graphical application look at https://github.com/Ultimaker/Cura which is the graphical frontend for CuraEngine.
9
10The CuraEngine can be used seperately or in other applications. Feel free to add it to your application. But please take note of the License.
11
12License
13=======
14CuraEngine is released under terms of the AGPLv3 License.
15Terms of the license can be found in the LICENSE file. Or at http://www.gnu.org/licenses/agpl.html
16
17But in general it boils down to: You need to share the source of any CuraEngine modifications if you make an application with the CuraEngine. (Even if you make a web-based slicer, you still need to share the source!)
18
19How to Install
20==============
211. Clone the repository from https://github.com/Ultimaker/CuraEngine.git (the URL at the right hand side of this page).
222. Install Protobuf >= 3.0.0 (see below)
233. Install libArcus (see https://github.com/Ultimaker/libArcus)
24
25In order to compile CuraEngine, either use CMake or start a project in your preferred IDE. 
26CMake compilation:
27
281. Navigate to the CuraEngine directory and execute the following commands
292. ```$ mkdir build && cd build```
303. ```$ cmake ..```
314. ```$ make```
32
33Project files generation:
34
351. Navigate to the CuraEngine directory and execute the following commands
362. ```cmake . -G "CodeBlocks - Unix Makefiles"```
373. (for a list of supported IDE's see http://www.cmake.org/Wiki/CMake_Generator_Specific_Information#Code::Blocks_Generator)
38
39Building with MSVC
40------------------
41Building CuraEngine with the MSVC toolchain is similar to the cmake instructions above with a couple of extra options.
42- If libArcus is not installed to a location on your PATH you will need to pass the install location of the library using ```-DCMAKE_PREFIX_PATH```.
43- If you wish to statically link the C runtime pass ```-DMSVC_STATIC_RUNTIME=ON``` when configuring using cmake.
44    - Note that libArcus should also be built with this option as well or you will get linker errors.
45- Vcpkg may be used to install protobuf and cppunit (only required if you would like to build the CuraEngine test suite).
46
47Installing Protobuf (Linux)
48-------------------
491. Be sure to have libtool installed.
502. Download protobuf from https://github.com/google/protobuf/releases (download ZIP and unZIP at desired location, or clone the repo). The protocol buffer is used for communication between the CuraEngine and the GUI.
513. Run ```autogen.sh``` from the protobuf directory: 
52   ```$ ./autogen.sh```
534. ```$ ./configure```
545. ```$ make```
556. ```# make install```  
56   (Please note the ```#```. It indicates the need of superuser, as known as root, privileges.)
577. (In case the shared library cannot be loaded, you can try ```sudo ldconfig``` on Linux systems)
58
59Running
60=======
61Other than running CuraEngine from a frontend, such as Ultimaker/Cura, one can run CuraEngine from the command line.
62For that one needs a settings JSON file, which can be found in the Ultimaker/Cura repository.
63Note that the structure of the json files has changed since 2.1. In the corresponding branch of the Cura repository you can find how the json files used to be structured.
64
65An example run for an UM2 machine looks as follows:
66* Navigate to the CuraEngine directory and execute the following
67```
68./build/CuraEngine slice -v -j ../Cura/resources/definitions/dual_extrusion_printer.def.json -o "output/test.gcode" -e1 -s infill_line_distance=0 -e0 -l "/model_1.stl" -e1 -l "fully_filled_model.stl" 
69```
70
71Run `CuraEngine help` for a general description of how to use the CuraEngine tool.
72
73[Set the environment variable](https://help.ubuntu.com/community/EnvironmentVariables) CURA_ENGINE_SEARCH_PATH to the appropriate paths, delimited by a colon e.g.
74```
75CURA_ENGINE_SEARCH_PATH=/path/to/Cura/resources/definitions:/user/defined/path
76```
77
78Internals
79=========
80
81The Cura Engine is structured as mainly .h files. This is not standard for a C++ project. However, using less cpp files makes the optimizer work harder and removes linking error issues. It's partially a result of lazyness but comes in handy for optimizations.
82
83The .h files contain different steps called from the main.cpp file. The main.cpp file contains the global slicing logic.
84
85The slicing process follows the following global steps:
86* Load 3D model
87* Analize and fix 3D model
88* Slice 3D model into 2D layers
89* Build LayerParts from sliced layers
90* Generate Insets
91* Generate up/down skins areas
92* Generate sparse infill areas
93* Generate GCode for each layer
94
95Each step has more logic in it. But this is a general overview.
96All data for the engine is stored in the "SliceDataStorage". It's important to remember that only the data from the previous step is valid.
97
98Coordinates are stored in 64bit integers as microns in the code. So if you see a value of 1000 then this mean 1mm of distance. This is because Clipper works on 64bit integers and microns give a high enough resolution without limiting the size too much. Note that there are some bits and pieces of code that need to be careful about 64bit overflows, especially calculating lengths sqrt(x*x+y*y) can cause overflows.
99
100OptimizedModel
101==============
102The OptimizedModel is a 3D model stored with vertex<->face relations. This gives touching face relations which are used later on to slice into layers faster.
103
104Slicer
105======
106While usually the whole GCode generation process is called 'slicing', the Slicer in the CuraEngine is the piece of code that generates layers. Each layer contains closed 2D polygons.
107These polygons are generated in a 2 step process. First all triangles are cut into lines per layer, for each layer a "line segment" is added to that layer.
108Next all these line-segments are connected to each other to make Polygons. The vertex<->face relations of the OptimizedModel help to make this process fast, as there is a huge chance that 2 connecting faces also make 2 connecting line-segments.
109This code also patches up small holes in the 3D model, so your model doesn't need to be a perfect Manifold. It also deals with incorrect normals, so it can flip around line-segments to fit end-to-end.
110The slicing code is found in [slicer.cpp](src/slicer.cpp)
111
112After the Slicer we have closed Polygons which can be used in Clipper.
113
114LayerParts
115==========
116An important concept to grasp is the idea of LayerParts. LayerParts are seperate parts inside a single layer. For example, in a solid cube each layer has a single LayerPart. However, in a table the layers which cover the legs have a LayerPart per leg, and thus there will be 4 LayerParts.
117A LayerPart is a seperated area inside a single layer which does not touch any other LayerParts. Most operations run on LayerParts as it reduces the amount of data to be processed. During GCode generation handling each LayerPart as a separate step makes sure you never travel between LayerParts which reduces the amount of external travel.
118LayerParts are generated after the Slicer step.
119The code for generating LayerParts is found in [layerParts.cpp](src/layerPart.cpp)
120
121In order to generate the LayerParts, Clipper is used. A Clipper union with extended results gives a list of Polygons with holes in them. Each polygon is a LayerPart, and the holes are added to this LayerPart.
122
123Insets
124======
125Insets are also called "Perimeters" or "Loops" sometimes. Generating the insets is only a small bit of code, as Clipper does most of the heavy lifting.
126The code for generating insets is found in [WallsComputation.cpp](src/WallsComputation.cpp).
127
128Up/Down skin
129============
130The skin code generates the fully filled areas, it does this with some heavy boolean Clipper action. The skin step uses data from different layers to get the job done. Check the code for details.
131The sparse infill area code is almost the same as the skin code. With the difference that it keeps the other areas and uses different offsets.
132The code for generating skin areas is found in [skin.cpp](src/skin.cpp).
133
134Note that these steps generate the areas, not the actual infill lines. The infill line paths are generated later on. So the result of this step are lists of Polygons which are the areas that need to be filled.
135
136GCode generation
137================
138The GCode generation is quite a large bit of code. As a lot is going on here. Important bits here are:
139* PathOrderOptimizer: This piece of code needs to solve a TravelingSalesmanProblem. Given a list of polygons/lines it tries to find the best order in which to print them. It currently does this by finding the closest next polygon to print. The code for this is found in [pathOrderOptimizer.cpp](src/pathOrderOptimizer.cpp).
140* Infill: This code generates a group of lines from an area. This is the code that generates the actual infill pattern. There is also a concentric infill function, which is currently not used. The code for this is found in [infill.cpp](src/infill.cpp) and the [infill subfolder](src/infill/).
141* Comb: The combing code is the code that tries to avoid holes when moving the head around without printing. This code also detects when it fails. The final GCode generator uses the combing code while generating the final GCode. So they interact closely. The combing code is found in [pathPlanning/Comb.cpp](src/pathPlanning/Comb.cpp)
142* GCodeExport: The GCode export is a 2 step process. First it collects all the paths for a layer that it needs to print, this includes all moves, prints, extrusion widths. And then it generates the final GCode. This is the only piece of code that has knowledge about GCode keywords and syntax to generate a different flavor of GCode it will be the only piece that needs adjustment. All volumatric calculations also happen here. The code for the GCode export is found at [FffGcodeWriter.cpp   ](src/FffGcodeWriter.cpp)
143