3DCoat Python API
The 3DCoat Python API documentation.
|
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.
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:
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.
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
Any object like vec2, vec3, vec4, mat..., any other may be copied as reference or as value. If you write something like this:
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:
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.
The addons mechanism is a way to extend the 3DCoat functionality and share it with another users. Since the 3DCoat 2024 there is Addons menu in the main menu. Get there, see the Examples section, look the Readme. You may add own scripts into that menu. Click the "..." button in any submenu and see the available options. You may add own submenu, script, readme, license, funding information, links. Also, you may create redistributable packages right in that menu. If user installs the package the corresponding scripts will appear in the Addons menu. Hotkey may be assigned to any script. Addons menu follows the folders 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 it's additional files should be placed in the separate folder. That folder will not be shown in the Addons menu, only the scripts itself will be referred.
Looking the examples is the best way to understand the API. Use Scripts->Create new Python script to experiment with that examples.