Using the SDK¶
Python versions¶
This SDK is supported for Python versions 3.5.2+, 3.6.0+, 3.7.0+ and 3.8.0+. Other versions are not supported and may not work properly.
Note
Python 64bit is needed for directly accessing a .p3d file. It will not work with 32bit version.
SDK path¶
When using the SDK from Patchwork 3D, the path to the SDK is already correctly set.
If you want to use the SDK directly from a custom Python interpreter (outside Patchwork 3D),
you need to modify your PYTHONPATH
to include the following directories:
Patchwork 3D install directory
1 (only needed if using theP3DFile
API)Patchwork 3D install directory\python\Lib\site-packages
1
This can be done by adding these paths in PYTHONPATH
environment variable.
It can also be done by adding these lines in your scripts, before importing the SDK :
import sys, os
# Put your version of Patchwork 3D
P3D_PATH = r"C:\Program Files\Lumiscaphe\Patchwork 3D 2020.1 X4 release 1"
sys.path.append(P3D_PATH)
sys.path.append(os.path.join(P3D_PATH, "python", "Lib", "site-packages"))
Note
You can also copy Patchwork 3D install directory\python\Lib\site-packages\p3dsdk
elsewhere to use it independently of Patchwork 3D
(for example for controlling Patchwork 3d from another computer or another platform).
You will not be able to use the P3DFile
API without setting PYTHONPATH
to Patchwork 3D install directory, however.
Controlling a Patchwork 3D instance¶
For controlling Patchwork 3D from Python, a HTTP connection is used. Two classes let you connect to an instance of Patchwork 3D:
P3DSession
for specifying host and port for the connectionCurrentP3DSession
for using the current Patchwork 3D instance when executed from Patchwork.
The interpreter can be Patchwork's interpreter or an externally launched interpreter.
Note
Some settings of Patchwork 3D are not applied when scripting. For example, name uniqueness can be enforced when renaming objects from UI (depending on settings) but it is not enforced when renaming objects using scripting.
Using Patchwork 3D Python interpreter¶
A Python interpreter is launched with Patchwork 3D. This interpreter is used when executing a script from Patchwork (console ( menu).
menu) or when using theUse CurrentP3DSession
to connect to the Patchwork 3D instance executing the script.
Note
You can set a custom interpreter to launch in Patchwork's Settings. A custom Python interpreter lets you use third party Python packages easily (e.g by using pip to manage your packages).
Using External Python interpreter¶
First you need to set the correct PYTHONPATH
for using the SDK (see SDK path).
Then you need to put Patchwork 3D in listening mode using
menu and selecting a port. You can also allow remote connections (from another computer) to this instance.You can then connect to the Patchwork 3D instance by using the IP address of the computer running the
Patchwork 3D instance and the port chosen (by default 33900) with P3DSession
class.
Note
When trying to connect to Patchwork 3D instance remotely, don't forget to open the chosen port in your firewall and/or do port forwarding on your router if needed.
Accessing a .p3d file directly¶
Availability: Windows only, with Python 64bit.
It is possible to read/write a .p3d database directly, without using Patchwork 3D. The API is limited to the Data API. It can be useful for quickly batch processing multiple databases.
Use the methods P3DFile.create()
and P3DFile.open()
to respectively
create or open a database. The recommended way to use these methods is through
the with
keyword:
with P3DFile.open("database.p3d") as database:
# Do what you want with database
database.save()
# When exiting of the block, the database has been closed automatically
with P3DFile.create() as database:
# Do what you want with database
database.save_as("database.p3d")
# When exiting of the block, the database has been closed automatically
Note
If you are not using the with
keyword, make sure to close the
database with the Database.close()
method, otherwise the file
will be locked until the Python process has exited.
The database version compatibility is the same as the Patchwork 3D from which the SDK is used. For example, if using the SDK of Patchwork 3D 2020.1 X4, you can open databases created with Patchwork 3D versions up to 2020.1 X4 and created databases will be 2020.1 X4 databases.
Footnotes