.. py:module:: p3dsdk
   :noindex:

=============
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 :ref:`directly accessing a .p3d file <p3d_file_access>`.
   It will not work with 32bit version.

.. _sdk_path:

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 :envvar:`PYTHONPATH` to include the following directories:

* :file:`{Patchwork 3D install directory}`\ [#p3d_path]_ (only needed if using the :py:class:`P3DFile` API)
* :file:`{Patchwork 3D install directory}\\python\\Lib\\site-packages`\ [#p3d_path]_

This can be done by adding these paths in :envvar:`PYTHONPATH` environment variable.

It can also be done by adding these lines in your scripts, before importing the SDK :

.. code-block:: python3

   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, os.path.join(P3D_PATH, "python", "Lib", "site-packages"))


.. note::
   You can also copy :file:`{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 :py:class:`P3DFile` API without setting :envvar:`PYTHONPATH`
   to Patchwork 3D install directory, however.


.. _p3d_rest:

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:

* :py:class:`P3DSession` for specifying host and port for the connection
* :py:class:`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 (:menuselection:`S&cripting --> Execute script` menu) or when using the :doc:`console <console>`
(:menuselection:`S&cripting --> Console` menu).

Use :py:class:`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 :program:`pip` to
   manage your packages).

Using External Python interpreter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First you need to set the correct :envvar:`PYTHONPATH` for using the SDK (see :ref:`sdk_path`).

Then you need to put Patchwork 3D in listening mode using
:menuselection:`S&cripting --> 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 :py:class:`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.


.. _p3d_file_access:

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 :doc:`Data API <api/api.data>`.
It can be useful for quickly batch processing multiple databases.

Use the methods :py:meth:`P3DFile.create()` and :py:meth:`P3DFile.open()` to respectively
create or open a database. The recommended way to use these methods is through
the :keyword:`with` keyword:

.. code-block:: python3

   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

.. code-block:: python3

   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 :keyword:`with` keyword, make sure to close the
   database with the :py:meth:`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.


.. rubric:: Footnotes

.. [#p3d_path] The install location of Patchwork 3D is usually of the form :file:`C:\\Program Files\\Lumiscaphe\\Patchwork 3D {XXXX}.{Y} X{Z} release {N}`