building.rst

Building from sources

There is 2 way in which you can build the project:

1. As a CloudCompare Plugin
2. As "standalone" Python packages

When built as CloudCompare plugin, at the end of the process, you will have a standard CloudCompare plugin that embeds Python to allow running Python script directly in the app and allow scripts to interact with the currently running CloudCompare like a regular C++ plugin would. The plugin built, also embeds various Python bindings of CloudCompare's libraries to be used in your script.

When build as standalone packages, you will install the Python bindings of the CloudCompare's libraries in your Python environment.

The process to build is explained in the sections below.

Building as Plugin

Supported platforms: [Windows, Linux, macOS]

In the following sections we assume that you know how to compile CloudCompare from source, otherwise refer to the CloudCompare documentation on how to do.

To compile this plugin you need to have Python installed.

This plugin is known to compile and work with CloudCompare commit d17314ca8538e187bf12d4ebe97525d61886b735.

Python 3.9 or more is required to build as a plugin.

Windows

1. Clone this project into CloudCompare/plugins/private

2. Create a virtual environment via venv or conda

   # Python's venv
   python -m venv .\pyccvenv
   
   # Conda environment
   conda create -n pyccenv
   

3. Activate the environment

   # Python's venv (PowerShell)
   .\pyccenv\Scripts\Activate.ps1
   
   # Conda environment
   conda activate pyccenv
   

4. install dependencies

   pip install -r requirements-release.txt
   

5. Generate the cmake config

   To generate the cmake config you have 2 options:

   1. Start the cmake generation while still within the activated environment

   2. Add -DPYTHON_EXECUTABLE="somepath_to_python.exe" Where somepath_to_python.exe is the absolute path to the python executable of the pyccenv created earlier.

      To get it, run: python -c "import sys;print(sys.executable)" (while in the activated env)

   In both cases the cmake option to add in order to build the plugin in -DPLUGIN_PYTHON=ON

6. Build

7. Install

Linux

1. Clone this project in CloudCompare/plugins/private

2. Install additional dependencies

   Ubuntu: libpython3-dev and pybind11-dev (only available since 20.04)

   Fedora: python3-devel and pybind11-devel

3. Run cmake with -DPLUGIN_PYTHON=ON

4. Build

5. Install

macOS

1. Clone this project in CloudCompare/plugins/private

2. Make sure you have python3 installed (and Qt)

3. Install additional dependencies

   In this example, we will use brew brew install pybind11

4. Run cmake with -DPLUGIN_PYTHON=ON

5. Build

6. Install

Building as independent wheels

Supported platforms: [Windows, Linux, macOS]

It is also possible to build and install the bindings as standard python packages to use them in python scripts (run by a standalone python executable and not the embedded python in the plugin).

To build as standalone wheels, it is not necessary to clone the repo in CloudCompare's plugins/private folder.

Important

To be able to pip install from source, you need pip version >= 21.1 Run pip install --upgrade pip to get the latest version

To do so:

1. Clone this project
2. Set path to Qt (Windows/macOS)

# Windows (PowerShell)
$env:CMAKE_PREFIX_PATH+=";C:\Qt\5.15.2\msvc2019_64"

macOS (bash)
export CMAKE_PREFIX_PATH=/usr/local/opt/qt@5

3. Run

# Building the wheels

pip wheel --no-deps wrapper/cccorelib
pip wheel --no-deps wrapper/pycc

# Installing directly

pip install wrapper/cccorelib
pip install wrapper/pycc

Supported CloudCompare Plugins

Some CloudCompare plugins (the ones in C++) are available through python. And are compiled only if the corresponding C++ plugin is also being compiled.

Currently the only available "plugin wrapper" is one for qM3C2 plugin.

To compile this wrapper do:

Building as Plugin

Add -DPLUGIN_STANDARD_QM3C2=ON to the cmake configuration.

Building as independent wheels

Before the pip command, add -DPLUGIN_STANDARD_QM3C2=ON to the SKBUILD_CONFIGURE_OPTIONS environment variable.

export SKBUILD_CONFIGURE_OPTIONS="-DPLUGIN_STANDARD_QM3C2=ON"

Other development related things

This section is only interesting for maintainers.

Running the tests

Tests works by running CloudCompare in command line mode. To run them, you need pytest, and you need to provide to pytest the path the where CloudCompare is installed

# in CloudCompare/plugins/private/CloudCompare-PythonPlugin:

pytest --cloudcompare_exe "C:\CMakeBuilds\CloudCompare\Release\install\CloudCompare\CloudCompare.exe" tests

Building the documentation

Building the documentation also works by running CloudCompare in command line mode. To build the documentation:

cd docs
.\make-docs.ps1 "C:\CMakeBuilds\CloudCompare\Release\install\CloudCompare\CloudCompare.exe"

Which by default will build the docs in HTML in docs/_build. Open docs/_build/index.html to view it. (The output dir can be changed using the -OutputDir option)

Building the Windows Installer

Building the Windows installer requires the following:

• PowerShell Core (To run the creation script).
• Wix Toolset version 3.x (The actual toolset that creates the installer)
• Your custom built CloudCompare (with the Python Plugin) must have been installed. In other words the install target (cmake --install .) must have been done.

To create the installer, go in the installer directory and start the ./Create-Installer.ps1 script and give it as the first positional argument the absolute path to the directory where your custom built CC was installed.

Example:

# in "installer" folder:
./Create-Installer "C:\CMakeBuilds\CloudCompare\Release\install\CloudCompare"
# or
pwsh ./Create-Installer "C:\CMakeBuilds\CloudCompare\Release\install\CloudCompare"

Note

A custom cmake target (that can be launched from your IDE or command line) is available in Release build to create the installer for you (it simply calls the script with the correct parameters).

cmake --build build_dir --target python_plugin_installer .