Description

The 3DCoat Python API is intended to trigger UI commands, operate over the scene, and create new tools. It is very similar to the C++ Core API, but has its own advantages and drawbacks.

No need for any additional setup to make your scripts; Python is embedded into the 3DCoat distributive.
Python is like a Swiss-knife, allowing you to bring the whole power of Python libraries into 3DCoat.
Python is much slower than C++, so it may be used only for general management, not for deep and complex algorithms.
If you are already familiar with the C++ Core API, the Python API is very similar, almost 1:1, with the same logic and function names.

Usage

Use Scripts->Create Python Script to create a new script. You may choose an initial template to start. The .py file will open in your current editor associated with .py files.
We use embedded Python 3.8.10 to operate. This is the last Python version that may run on Windows 7.
If needed, you may create a file called requirements.txt with a list of used modules; in this case, the modules will be auto-installed before the script runs.
We recommend Visual Studio Code, as it will automatically recognize 3DCoat-specialized commands syntax and offer the correct hints.
Pay attention: the file coat.pyi located in the project folder is responsible for the coat module hints in Visual Studio Code. You may open that file, as it contains the list of all classes and commands, which may be helpful for quick reference.
Use Scripts->Show Python Console to see the console output from Python. Don't close the console window, it will close the whole 3DCoat! See the Debugging section to understand the debugging with the VisualStudio Code.
You may install additional modules for Python using Scripts->Install Python Modules. Another way is to use requirements.txt in the same folder as the .py file's location.

Debugging

You can debug the Python script using Visual Studio Code. Create the project using Scripts -> Create Python Script. The project consists of your_project_name.py (your script), coat.pyi (the coat commands list), and launch.json in the .vscode folder (run/debug settings). Older versions of 3DCoat was not making the launch.json, in this case, you may create it manually or re-create the project with the latest version of the 3DCoat. The content of the launch.json file is:

Click to see the content of the launch.json file

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Attach",
            "type": "python",
            "request": "attach",
            "processId": "${command:pickProcess}",
            "justMyCode": false
        }
    ]
}

The project will open in Visual Studio Code if it is installed. You may also open the project folder manually from VS Code.

Now return to 3DCoat, click Scripts -> Attach to the Python Debugger. Then go to VS Code.
In VS Code, select the .py file, then press F5 to start debugging. A dropdown list will appear; select 3DCoatGL64.exe.
VS Code will try to connect to the 3DCoat process. Usually it happens immedialely, if attached successfully, you will see the debugging controls at the top: . If the attachment fails, you will see an error message; try to connect again via F5. If you connect successfully, press Finish in 3DCoat.

Now set breakpoints in VS Code, then run your script from 3DCoat's scripts menu. The script will stop at the breakpoint. Now you may watch variables, debug step by step, etc.

Main classes

General I/O: coat.io
Dialog management: coat.dialog
Mesh operations: coat.Mesh
Retopo/Modeling operations: coat.Model
UV operations: coat.uv
Scene roots: coat.Scene
Scene element: coat.SceneElement
Volume management: coat.Volume
UI management: coat.ui
2D-vectors math: coat.vec2
3D-vectors math: coat.vec3
4D-vectors math: coat.vec4
3D-matrix math: coat.mat3
4D-matrix math: coat.mat4
Bounds management: coat.box
Rectangles management: coat.rect
Symmetry management: coat.symm
Resources management: coat.resource
Settings: coat.settings

Copy vs Reference

Any object like vec2, vec3, vec4, mat..., any other may be copied as reference or as value. If you write something like this:

from coat import *
v1=vec3(1,2,3)
v2=v1
v2.x=5
print(v1.x, v2.x)

You will see 5.0 5.0, because v1 and v2 are the same object. If you want to copy the object as value, you should write something like this:

from coat import *
v1=vec3(1,2,3)
v2=vec3(v1)
v2.x=5
print(v1.x, v2.x)

You will see 1.0 5.0, because v2 is a copy of v1.
This is true for almost all 3DCoat's objects (where is has logical sense), not only for vectors.

Addons

The add-on mechanism is a way to extend the 3DCoat functionality and share it with another user. Since the 3DCoat 2024, there has been an Addons menu in the main menu. Get there, see the Examples section, and look at the Readme. You may add your own scripts to that menu. Click the "..." button in any submenu and see the available options. You may add your submenu, script, readme, license, funding information, and links. Also, you may create redistributable packages right in that menu. If a user installs the package, the corresponding scripts will appear in the Addons menu. Hotkey may be assigned to any script. The Addons menu follows the folder structure in the UserPrefs/Addons/ folder. Exception is folders and files that start from "." or "_". They are ignored. Both - CoreAPI and Python scripts may be placed in the Addons menu. Each script and its additional files should be placed in a separate folder. That folder will not be shown in the Addons menu, only the scripts itself will be referred.

Using muliple files in the project

It is important not to place the additional data files right in the folder with the main .py file. We recommend placing them in a subfolder like "_data". You can place additional .py files in the same folder as the main .py file or in a subfolder. If you prefer these to not appear in the Addons, place them in a folder that starts with "_" or prefix the submodule filenames with "_", such as "_my_submodule.py". Submodules can be imported as follows:

import _my_submodule
# or
from _my_submodule import *
# or, if the submodule my_submodule.py is located in a folder named _my_folder
from _my_folder import my_submodule

Note that when you run the main .py files, the submodules are not reloaded if they have already been loaded. To reload a submodule, you should use the reload function from the importlib module:

import _my_submodule
# To reload the _my_submodule during development, use the following snippet. 
# This can be removed once development is completed.
import importlib
importlib.reload(_my_submodule)

In the case of a submodule located in a subfolder, you should use the following snippet:

from _my_folder import my_submodule
# The reloading code:
import importlib
importlib.reload(my_submodule)

Console Usage

You can use the console to view the output of the print() function. The console can be opened via Scripts -> Show Python Console. However, you can also open it directly from a script using the coat.io.showPythonConsole() function. In this case, the console pops up and will be cleared automatically. This is useful for debugging purposes.

Examples

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

Basic

HelloWorld.py
The Hello World!

insert_in_menu.py
Insert item into the menu!

insert_in_toolset.py
Insert item into the toolset!

ui_command.py
The UI management example.

dialogs.py
The dialog creation example.

resources_test.py
Resources management (Alphas, Stencils, ....)

Scene

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

Meshes

meshes_primitives.py
Meshes and primitives

cut_by_plane.py
Break the object into pieces

Break_mesh_by_cracks.py
Break the current volume with realistic cracks

Generators

GeneratorExample.py
Non-destructive geometry generator example

Primitives

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

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

HelloWorld3D.py
Generate the text primitive

UV

uv_to_sculpt.py
Get UV-s from the UV room and convert them to the sculpt room objects

uv_random_rotation.py
Randomly rotate the UV islands and pack them

uv_to_cloth.py
Convert uv islands to the cloth pieces with extra borders to be sewed together

uv_stats.py
Calculate the square thash for the UV islands

Modeling

random_spheres.py
create random spheres in retopo room, then remove one of groups, collapse edges randomly

hairy_sphere.py
This is example just to discover operations over meshes in the retop room. There we create random spheres in retopo rool, delete one of groups, select random faces, extrude them and move along normals.

virus.py
Low-poly virus modeling

Export

Autoexport.py
The script used for the File->Export->Decimate > Auto UV-Map > Export

Render

render_with_shadow.py
Render object from the random top view with random light position. The object rendered as if it drops the shadow on the invisible plane. The shadow represented as the alpha channel of the final image.