Pix4Dengine SDK Quick-Start

Prerequisites

The use of Pix4Dengine SDK requires some familiarity with the Python programming language.

Installation requirements

Pix4Dengine SDK must be installed onto one of the supported platforms:

OS/Distribution Python
Linux/Ubuntu 18.04 64bit 3.6 64bit
Windows 10, Server 2016 64bit 3.6 64bit

Installation

Linux/Ubuntu 18.04

Pix4Dengine SDK can be obtained as a Debian software package from its download page.

It is installed system-wide by executing in a terminal:

sudo apt-get update
sudo apt-get install ./python3-pix4dengine_1.4.0_amd64.deb

Note that sudo privileges are needed to run these commands. If not already installed, the correct version of Python will be automatically installed.

Windows

Pix4Dengine SDK can be obtained as a wheel package from its download page.

Before installing it, make sure Python 3.6 (including pip) is installed. Install Pix4Dengine SDK by executing in a command interpreter:

pip install pix4dengine_1.4.0-cp36-cp36m-win_amd64.whl

Basic usage of Pix4Dengine SDK

The code sample below shows the simplest case of processing using Pix4Dengine. The code ensures the use of Pix4Dengine is authorised by the Pix4D license server, creates a project with default parameters and calibrates the cameras in the project. The calibration quality report is then loaded, and the quality status summary is printed.

Note

The code must be structured as explained here.

from pix4dengine import create_project, login_seat
from pix4dengine.pipeline import Pipeline
from pix4dengine.exports import get_report


def run(proj_name, image_dirs):
    # Create a project
    project = create_project(proj_name, image_dirs=image_dirs)

    # Calibrate the cameras in the project
    pipeline = Pipeline(algos=["CALIB"])
    pipeline.run(project)

    # Access the calibration quality report
    return get_report(project)


def main(email, password, license_key):
    # Acquire the authorization to use Pix4Dengine from the Pix4D licensing system
    login_seat(email, password, license_key)

    quality_report = run("test_survey", path_to_directory_with_images)

    print(quality_report.calibration_quality_status())


if __name__ == "__main__":
    main(YOUR_EMAIL, YOUR_PASSWORD, YOUR_LICENSE_KEY)

Logging system

For technical reasons, Pix4Dengine SDK uses two log systems: a high-level, configurable one for SDK activity, and a log generated by the core processing algorithms.

SDK activity log

The Pix4Dengine SDK configurable log uses Python’s built-in logging module. If you want to see detailed messages from the SDK, then you have to configure the logging for your application.

For a number of recipes related to logging please visit Python logging cookbook.

Example of configuration:

"""Module setting up the logging infrastructure."""
import logging
from logging.config import dictConfig


LOGGING_CONFIG = dict(
    version=1,
    formatters={"f": {"format": "%(asctime)s %(name)-26s %(levelname)-8s %(message)s"}},
    handlers={"h": {"class": "logging.StreamHandler", "formatter": "f", "level": logging.INFO}},
    root={"handlers": ["h"], "level": logging.INFO},
)

dictConfig(LOGGING_CONFIG)

Processing core log file

The core processing algorithms log information to a file. This log can be useful for de-bugging, and is similar to the Pix4Dmapper log. The Pix4Dengine project property logfile_path may be used to obtain the path of this log file for a given processing project.

Thread safety

Pix4Dengine SDK does not guarantee thread safety. If the code that uses the SDK is multi-threaded, it is the user’s responsibility to ensure thread safety of the code.

Multiprocessing

To isolate the main Pix4Dengine SDK process from issues caused by resource-intensive processing tasks, these are launched in their own, separate sub-process. This places an important restriction on the code launching these processing tasks: it must not launch the processing directly from a global context. In other words, it must be possible to import any script that launches processing without the processing being launched automatically. This restriction is well aligned with good practices for python main scripts.

Here, we illustrate this with an example of a non-conforming script and equivalent conforming one. This is non-conforming script script.py:

from pix4dengine import open_project
from pix4dengine.pipeline import Pipeline

project = open_project("project")
pipeline = Pipeline()
pipeline.run(project)

Importing this script (python -c "import script") results in the pipeline being run automatically. Behind the scenes, the pipeline will spawn a process, and import the script into that process, resulting in a potentially infinite recursion and raising a RuntimeError. Instead, script.py should have this structure:

from pix4dengine import open_project
from pix4dengine.pipeline import Pipeline

def processing():
    project = open_project("project")
    pipeline = Pipeline()
    pipeline.run(project)

if __name__ == "__main__":
    processing()

this structure ensures the processing code is only launched when the script executed. You can find further explanation of restrictions in the multiprocessing module documentation.