Using the SDK

Python versions

This SDK is supported for Python versions 3.7.0+, 3.8.0+ and 3.9.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 directory1 (only needed if using the P3DFile API)

  • Patchwork 3D install directory\python\Lib\site-packages1

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 connection

  • CurrentP3DSession 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 (Scripting ‣ Execute script menu) or when using the console (Scripting ‣ Console menu).

Use 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 Scripting ‣ Start scripting server 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

1(1,2)

The install location of Patchwork 3D is usually of the form C:\Program Files\Lumiscaphe\Patchwork 3D XXXX.Y XZ release N