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.