API Documentation

Processing

Interface to the processing executable

Interface to the Pix4Dmapper executable to use the photogrammetry libraries.

class pix4dengine.enginewrapper.EngineWrapper(base_command=None, *, credentials=None, max_cpus=-1)

Class providing low-level access to pix4dmapper or pix4dmapper.exe.

Parameters:
  • base_command (Union[str, List[str], None]) – local path to pix4dmapper or pix4dmapper.exe. Alternatively, a list of str defining the command needed to execute Pix4Dmapper (e.g., ssh server /opt/bin/pix4dmapper). If not given, the default executable location is used. See pix4dengine.settings for changing the default.
  • credentials (Optional[Credentials]) – login email and password for Pix4Dmapper.
  • max_cpus (int) – limit the maximum number of CPUs used by Pix4Dmapper.
HISTORY_SIZE

To find an error we will store just last HISTORY_SIZE messages from executable. If it is not specified or is None, the history may grow to an arbitrary length.

Note

The GPU is used automatically if the operating system and the graphic card are supported. Refer to the support pages for details on supported architectures and recommended hardware.

HISTORY_SIZE = 1000
create(p4d_path, images_dir, *, template=None, external_geoloc=None)

Create a new project.

Parameters:
  • p4d_path (str) – a valid path to the .p4d file
  • images_dir (str) – a valid path to the directory containing the images
  • template (Union[ProcessingTemplate, str, None]) – use an optional pre-defined template to create the project. The template can be a ProcessingTemplate object, or a .tmpl file (passed as a str), generated by the Pix4Dmapper.
  • external_geoloc (Optional[ExternalGeolocation]) – use an external CSV file to geolocate the project images. Refer to the support web site for details.
Return type:

CompletedProcess

Returns:

An instance of subprocess.CompletedProcess, which runs the Pix4Dmapper command creating the project.

interactive_login(max_retries=3)

Acquire the authorization to use Pix4Dmapper interactively.

Parameters:max_retries (int) – maximum number of retries
Raises:LoginError on failure
is_logged_in()

Check if the user is authorized to run Pix4Dmapper by the Pix4D licensing system.

Return type:bool
Returns:True if authorized, False otherwise.
login(email, password)

Acquire the authorization to use Pix4Dmapper from the Pix4D licensing system.

Parameters:
  • email (str) – login email
  • password (str) – login password
Raises:

LoginError on failure

Return type:

None

logout()

Log out of the current session.

Raises:LogoutError on failure.
process(p4d_path, step, on_error=<function EngineWrapper.<lambda>>)

Process an existing project.

Parameters:
  • p4d_path (str) – a valid path to the p4d file
  • step (ProcessingStep) – define which processing step will be executed, passing an instance of ProcessingStep
  • on_error (Callable) – a callable to be exectued on_error.
Raises:

ProjectProcessingError on failure.

Return type:

None

split(p4d_path, max_n_images)

Split a project into sub-projects.

Parameters:
  • p4d_path (str) – a valid path to the p4d file
  • max_n_images (int) – the maximal number of images in a sub-project
Return type:

CompletedProcess

Returns:

An instance of subprocess.CompletedProcess, which executed the Pix4Dmapper command for splitting the project

version

Pix4Dmapper version in use.

Return type:str
class pix4dengine.enginewrapper.EngineTask(step, engine, project, *, callbacks=Callbacks(on_start=<function Callbacks.<lambda>>, on_success=<function Callbacks.<lambda>>, on_error=<function Callbacks.<lambda>>), config=None, validator=None)

Task to be executed using Pix4Dmapper.

Parameters:
  • step – define which processing step will be executed, passing a ProcessingStep.
  • engine_wrapper – the EngineWrapper to be used for processing the project.
  • project – the project to be processed, identified by an instance of Project
  • callbacks – optional callback bundle with functions to execute before work is started, after work is finished without errors, or in the event of an error. Callbacks are defined via an instance of Callbacks.
  • config – dictionary containing configuration options for the task, in the form {option: value}, e.g., {AlgoOption.CameraCalibration.MATCH_GEOMETRICALLY_VERIFIED, False}.
  • validator – a callable that can be used for validating the project report, based on user-defined quality requirements. validator will be called after each processing step, passing it the quality Report as argument. If the return value of validator is False, a FailedValidation is raised, otherwise processing continues normally. If validator has a message attribute, this is used as the error message in the FailedValidation that is raised. By default, no check is performed and no exception is raised.
set_config(config)

Set the configuration of this task.

Parameters:config – dictionary containing configuration options for the task, in the form {option: value}, e.g., {AlgoOption.CameraCalibration.MATCH_GEOMETRICALLY_VERIFIED, False}.
class pix4dengine.enginewrapper.Pipeline(project, *, algos=('CALIB', 'DEF_PROC_AREA', 'DENSE', 'ORTHO'), engine=None)

Standard Pix4D photogrammetry pipeline.

By default, this pipeline performs the camera calibration, adds a default processing area including all cameras, then runs the point cloud densification and orthomosaic steps used in the Pix4Dmapper. The tasks to be run can however be modified or removed by the user, or new ones can be defined and added. See set_default_proc_area() for details on the default processing area defintion.

Initialise a pipeline.

Parameters:
  • project – the Project instance on which to operate.
  • algos – a sequence of tasks to be executed, identified by the strings listed in STD_ALGOS. Note that, for running a single task, one must still provide a sequence of strings as, e.g., algos=("CALIB", ). If not set, the default photogrammetry pipeline is executed.
  • engine – optionally, one can pass the EngineWrapper to be used instead of the default one. See pix4dengine.settings for changing the default.
STD_ALGOS = ('CALIB', 'DEF_PROC_AREA', 'DENSE', 'ORTHO')

Utilities for the usage of EngineWrapper.

class pix4dengine.utils.enginewrapper.CallbackMessage

Container for callback return messages.

This object is passed to on_error callbacks if an error is detected while running an EngineWrapper for processing. See Callbacks.

Parameters:
  • message – a string containing a human-readable message, describing the error and, if possible, its cause.
  • pix4d_error_code – if available, the error code returned by Pix4Dmapper.

Create new instance of CallbackMessage(message, pix4d_error_code)

message

Alias for field number 0

pix4d_error_code

Alias for field number 1

class pix4dengine.utils.enginewrapper.Callbacks(on_start=<function Callbacks.<lambda>>, on_success=<function Callbacks.<lambda>>, on_error=<function Callbacks.<lambda>>)

Container of callbacks for EngineWrapper.

Example

Callbacks(on_start=lambda: print("Start processing"), on_success=[func2, func3])

In this case the lambda function will be called just before execution of some command, func2 and func3 will be called just after the completion of the command if the latter is succesful.

A callback slot also exists for on_error. Callbacks in this slot can optionally accept a CallbackMessage, which will contain human-readable information concerning the event which caused the error. Currently, the on_error callback can only be triggered during the processing of a project.

class pix4dengine.utils.enginewrapper.Credentials

Store for the credentials of the Pix4D licensing system to use Pix4Dmapper.

Example

Credentials(email="example@example.net", password="foobar")

Create new instance of Credentials(email, password)

email

Alias for field number 0

password

Alias for field number 1

Functions supporting the most common operations

Pix4Dengine Python SDK.

pix4dengine.create_project(proj_name, images_dir, engine_wrapper, *, template=None, work_dir='.', callbacks=<pix4dengine.utils.enginewrapper.Callbacks object>, external_geoloc=None)

Create a new project.

Parameters:
  • proj_name (str) – project name, it must contain only alphanumerical, hyphen or underscore characters. It should not start with an hyphen.
  • images_dir (str) – path to the directory containing the images.
  • engine_wrapper (EngineWrapper) – the EngineWrapper to be used for creating the project
  • template (Union[ProcessingTemplate, str, None]) – pre-defined template used for creating the project. The template can be a ProcessingTemplate object, or a .tmpl file (passed as a str), generated by the Pix4Dmapper.
  • work_dir (str) – the work directory, defining where the project is created.
  • callbacks (Callbacks) – optional callback bundle with functions to execute before work is started, after work is finished without errors, or in the event of an error. Callbacks are defined via an instance of Callbacks.
  • external_geoloc (Optional[ExternalGeolocation]) – a ExternalGeolocation instance, to use a CSV file for geolocating the project images.
Return type:

Project

Returns:

an instance of Project if the project is successfully created.

Raises:
pix4dengine.open_project(proj_name, work_dir='.')

Open an existing project.

Parameters:
  • proj_name (str) – project name, it must contain only alphanumerical, hyphen or underscore characters. It should not start with an hyphen.
  • work_dir (str) – directory where the project is located.
Return type:

Project

Returns:

an instance of Project if the project is successfully opened.

Raises:
pix4dengine.process_project(project, engine_wrapper, steps, *, callbacks=<pix4dengine.utils.enginewrapper.Callbacks object>, validator=<function <lambda>>)

Process an existing project.

Parameters:
  • project (Project) – the project to be processed, identified by an instance of Project
  • engine_wrapper (EngineWrapper) – the EngineWrapper to be used for processing the project
  • steps (Union[Sequence[ProcessingStep], ProcessingStep]) – define which processing steps will be executed, passing a single one or a sequence of steps. Steps are defined using ProcessingStep
  • callbacks (Callbacks) – optional callback bundle with functions to execute before work is started, after work is finished without errors, or in the event of an error. Callbacks are defined via an instance of Callbacks.
  • validator (Callable) – a callable that can be used for validating the project report, based on user-defined quality requirements. validator will be called after each processing step, passing it the quality Report as argument. If the return value of validator is False, a FailedValidation is raised, otherwise processing continues normally. If validator has a message attribute, this is used as the error message in the FailedValidation that is raised. By default, no check is performed and no exception is raised.
Raises:
Return type:

None

pix4dengine.create_split_projects(proj_name, images_dir, engine_wrapper, n_images, *, template=None, work_dir='.', callbacks=<pix4dengine.utils.enginewrapper.Callbacks object>, external_geoloc=None)

Create a set of split projects.

Parameters:
  • proj_name (str) – project name: must contain only alphanumerical, hyphen or underscore characters. It should not start with an hyphen.
  • images_dir (str) – path to the directory containing the images.
  • engine_wrapper (EngineWrapper) – the EngineWrapper to be used for creating the split project
  • template (Union[ProcessingTemplate, str, None]) – use a pre-defined template to create the project. The template can be a ProcessingTemplate object, or a .tmpl file (passed as a str), generated by the Pix4Dmapper.
  • work_dir (str) – where to create the project
  • n_images (int) – hint for number of images per sub-project
  • callbacks (Callbacks) – optional callback bundle with functions to execute before work is started, after work is finished without errors, or in the event of an error. Callbacks are defined via an instance of Callbacks.
  • external_geoloc (Optional[ExternalGeolocation]) – a ExternalGeolocation instance to use a CSV file to geolocate the project images.
Raises:
Return type:

Sequence[Project]

Interface to a project

Module containing the Project class, used to define and configure project.

class pix4dengine.project.Project(proj_name, work_dir='.', version='UNKNOWN')

Class representing a project.

Note: for the most common use-cases, use the functions provided in the top-level module:
add_3d_gcp_with_marks(gcp, marks)

Add a 3D GCP to the current project.

Parameters:
  • gcp (GCP3D) – a GCP defined by a GCP3D object.
  • marks (Sequence[Mark]) – marks associated to this 3D GCP, as a sequence of Mark objects.
Raises:
  • ValueError – the id or the label of the 3D GCP is already in use.
  • Exception – less than two marks were provided.
Return type:

None

coord_sys

An instance of CoordSys.

get_list_of_3d_gcps()

Get the list of 3DGCPs in the project.

Return type:List[GCP3D]
get_list_of_images(remove_path=True)

Get the list of images in the project.

Return type:List[str]
get_option_value(option)

Get the value of an algorithmic or export option.

Parameters:option (Enum) – Either a pix4dengine.options.AlgoOption or a pix4dengine.options.ExportOption object.
Return type:Any
Returns:The value of the requested option.

Example

project.get_option_value(ExportOption.PCL_EXPORT_LAS) returns True or False.

Note

The value is returned in the expected type, i.e., boolean options are returned as bool type.

Raises:KeyError – the option value could not be determined for the project.
get_processing_area()

Get the processing area of the project.

Returns:if it does not exist. A tuple containing the list of pix4dengine.utils.project.PointXY and the pix4dengine.utils.project.MinMaxRange if it exists.
Return type:None
p4d_path

Full path to the p4d file.

Return type:str
proj_name

Project name.

Return type:str
proj_path

Project full path.

Return type:str
set_options(*option)

Set one or more algorithmic or export options.

Parameters:*option – one or more tuples of (option, value), where option is an option from pix4dengine.options.AlgoOption or pix4dengine.options.ExportOption, and value is to be assigned to that option.

Example:

project.set_options((ExportOption.PCL.LAS, True),
                    (ExportOption.MESH.FBX, True),
                    (AlgoOption.PCL.POINT_DENSITY, "Low"))
Raises:
  • KeyError – if the option is not found the p4d file.
  • TypeError – if the wrong type is passed to an option, or if an option cannot be changed.
  • ValueError – if value is outside the allowed min-max range.
Return type:

None

set_processing_area(points, height_interval=MinMaxRange(min=-9999.9, max=9999.9))

Add a sequence of points defining the processing area.

Any previous definition of the processing area is overwritten. points and height_interval are defined using x, y, z map coordinates.

Parameters:
  • points (Sequence[PointXY]) – a sequence of PointXY objects, defining the extent of the processing area horizontally.
  • height_interval (MinMaxRange) – a MinMaxRange object, defining the vertical extent of the processing area.
Raises:

ValueError – if less than 3 points are passed, or if the height_interval is badly defined.

Note

The points defining the horizontal processing area can be given in clockwise or counterclockwise order. However, the points must be given in either of the two orderings consistently. Consider, e.g., a processing area to be defined using four points (A, B, C, D) given in clockwise order. Equivalent definitions would be (D, C, B, A), (B, C, D, A), (C, B, A, D),… However, a sequence (A, C, B, D) is not equivalent, and would not be used correctly during processing. In short, connected points should be given one after the other.

Return type:None
version

Pix4Dmapper version used to create this project.

Return type:str
work_dir

Work directory.

Return type:str

Input and output

Processing constants

Constants used to define and configure the processing of a project.

class pix4dengine.constants.processing.ExternalGeolocation

Data class to use a CSV file to geolocate project images.

Parameters:
  • file_format – a ExternalGeolocationFormat instance describing the format of the CSV file.
  • file_path – path to the CSV file.

Create new instance of ExternalGeolocation(file_format, file_path)

file_format

Alias for field number 0

file_path

Alias for field number 1

class pix4dengine.constants.processing.ExternalGeolocationFormat

External geolocation formats.

LAT_LONG = "Latitude, Longitude, Altitude" file format
LONG_LAT = "Longitude, Latitude, Altitude" file format
class pix4dengine.constants.processing.ProcessingStep

Processing steps.

CALIB = camera calibration step
DENSE = point cloud densification step
ORTHO = orthomosaic step
class pix4dengine.constants.processing.ProcessingTemplate

Default processing templates.

Provided for compatibility with Pix4Dmapper templates. Refer to the support page for details.

AG_MODIFIED_CAMERA = Ag Modified Camera
AG_MODIFIED_CAMERA_RAPID = Ag Modified Camera - Rapid/Low Res
AG_MULTISPECTRAL = Ag Multispectral
AG_RGB = Ag RGB
AG_RGB_RAPID = Ag RGB - Rapid/Low Res
MAPS_3D = 3D Maps
MAPS_3D_RAPID = 3D Maps - Rapid/Low Res
MODELS_3D = 3D Models
MODELS_3D_RAPID = 3D Models - Rapid/Low Res
THERMAL_CAMERA = Thermal Camera
THERMOMAP_CAMERA = ThermoMAP Camera

Processing options

Options for configuring the algorithm, and for setting and accessing the output files.

class pix4dengine.options.AlgoOption

Algorithmic configuration options.

These options are described in a dedicated support page. Please look for the “p4dkey” reported here for each option.

class CameraCalibration

Algorithmic options for the camera calibration (initial step).

CALIBRATION_EXT_PARAM_OPT = p4dkey=externalParamOptimization, type=str, allowed_values=(None, Orientation, All)
CALIBRATION_INT_PARAM_OPT = p4dkey=internalParamOptimization, type=str, allowed_values=(None, Leading, All, AllPrior)
CALIBRATION_METHOD = p4dkey=calibrationMethod, type=str, allowed_values=(Standard, Alternative, GeolocationAndOrientation)
IMAGE_SCALE = p4dkey=imageScale, type=str, allowed_values=(0.125, 0.25, 0.5, 1, 2)
KEYPT_IMAGE_SCALE = p4dkey=keypointsImageScale, type=str, allowed_values=(Full, Rapid, Custom)
KEYPT_NUMBER = p4dkey=numberOfKeypoints, type=int, min=100, max=1000000, allowed_values=()
KEYPT_SEL_METHOD = p4dkey=keypointSelectionMethod, type=str, allowed_values=(Automatic, Custom)
MATCH_GEOMETRICALLY_VERIFIED = p4dkey=geometricallyVerifiedMatching, type=bool, allowed_values=()
MATCH_IMAGE_SIMILARITY_MAX_PAIRS = p4dkey=matchImageSimilarityMaxPairs, type=int, min=0, max=50, allowed_values=()
MATCH_MTP_MAX_IMAGE_PAIR = p4dkey=matchMtpMaxImagePair, type=int, min=0, max=100, allowed_values=()
MATCH_RELATIVE_DISTANCE_IMAGES = p4dkey=matchRelativeDistanceImages, type=float, min=0.0, max=100.0, allowed_values=()
MATCH_STRATEGY = p4dkey=matchStrategy, type=str, allowed_values=(AutoAerial, AutoOblique, Custom)
MATCH_TIME_MULTI_CAMERA = p4dkey=matchTimeMultiCamera, type=int, allowed_values=(0, 1)
MATCH_TIME_NB_NEIGHBOURS = p4dkey=matchTimeNbNeighbours, type=int, min=0, max=50, allowed_values=()
MATCH_USE_TRIANGULATION = p4dkey=matchUseTriangulation, type=bool, allowed_values=()
REMATCH = p4dkey=rematch, type=bool, allowed_values=()
REMATCH_STRATEGY = p4dkey=rematchStrategy, type=str, allowed_values=(Auto, Custom)
SKY_SEGMENTATION = p4dkey=automaticSkyMasking, type=bool, allowed_values=()
class Densification

Algorithmic options for the point cloud densification.

PCL_AUTO_LIMIT_CAMERA_DEPTH = p4dkey=pclLimitDepthAutomatically, type=bool, allowed_values=()
PCL_DENSITY = p4dkey=pclDensity, type=str, allowed_values=(High, Optimal, Low)
PCL_IMAGE_MULTISCALE = p4dkey=pclImageMultiscale, type=bool, allowed_values=()
PCL_IMAGE_SCALE = p4dkey=pclImageDownscaleFactor, type=int, min=0, max=3, allowed_values=()
PCL_MERGE_TILES = p4dkey=pclExportMergeTiles, type=bool, allowed_values=()
PCL_MIN_NO_MATCHES = p4dkey=pclMinNoMatches, type=int, min=2, max=6, allowed_values=()
PCL_USE_ANNOTATIONS = p4dkey=pclUseAnnotations, type=bool, allowed_values=()
PCL_USE_PROCESSING_AREA = p4dkey=pclUseProcessingArea, type=bool, allowed_values=()
PCL_WINDOWS_SIZE = p4dkey=pclWindowSize, type=int, allowed_values=(7, 9)
PCL_XYZ_DELIMITER = p4dkey=pclExportXYZDelim, type=str, allowed_values=(Space, Tab, Comma, Semicolon)
class Index

Algorithmic options for the index generation.

DOWNSAMPLING_METHOD = p4dkey=indexDownsamplingMethod, type=str, allowed_values=(Gauss, Median, 75%Quantile, Average, Min, Max, Warp)
POINT_SHP = p4dkey=indexExportPointSHP, type=bool, allowed_values=()
POINT_SHP_GRIDSIZE = p4dkey=indexExportPointSHPGridSize, type=int, min=1, max=10000, allowed_values=()
POLYGON_SHP = p4dkey=indexExportPolygonSHP, type=bool, allowed_values=()
POLYGON_SHP_GRIDSIZE = p4dkey=indexExportPolygonSHPGridSize, type=int, min=1, max=10000, allowed_values=()
RESOLUTION = p4dkey=indexResolution, type=int, allowed_values=()
class Mesh

Algorithmic options for the mesh generation.

DECIMATION_CRITERIA = p4dkey=meshDecimationCriteria, type=str, allowed_values=(Quantitative, Qualitative)
DECIMATION_STRATEGY = p4dkey=meshDecimationStrategy, type=str, allowed_values=(Sensitive, Aggressive)
GEN_3D_TEXT = p4dkey=meshGenerate3dTexturedMesh, type=bool, allowed_values=()
MAX_OCTREE_DEPTH = p4dkey=meshMaxOctreeDepth, type=int, min=5, max=20, allowed_values=()
MAX_TRIANGLES = p4dkey=meshMaxTriangles, type=int, min=100, max=20000000, allowed_values=()
RESOLUTION = p4dkey=meshResolution, type=str, allowed_values=(High, Medium, Low, Custom)
SAMPLE_DENSITY_DIVIDER = p4dkey=meshSampleDensityDivider, type=int, min=1, max=5, allowed_values=()
TEXTURE_COLOR_BALANCING = p4dkey=meshTextureColorBalancing, type=bool, allowed_values=()
TEXTURE_SIZE = p4dkey=meshTextureSize, type=int, allowed_values=(256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072)
TILED_OBJ = p4dkey=meshExportTiledOBJ, type=bool, allowed_values=()
class Ortho

Algorithmic options for the orthomosaic generation.

CONTOUR_BASE = p4dkey=contourBase, type=int, min=0, max=10000, allowed_values=()
CONTOUR_ELEVATION_INTERVAL = p4dkey=contourElevationInterval, type=float, min=0.001, max=10000.0, allowed_values=()
CONTOUR_MIN_LINE_SIZE = p4dkey=contourMinLineSize, type=int, min=4, max=1000, allowed_values=()
CONTOUR_RESOLUTION = p4dkey=contourResolution, type=float, min=0.001, max=10000.0, allowed_values=()
DSM_FILTER_SMOOTHING = p4dkey=dsmFilterUseSmoothing, type=bool, allowed_values=()
DSM_FILTER_SMOOTHING_TYPE = p4dkey=dsmFilterSmoothingType, type=str, allowed_values=(Smooth, Medium, Sharp)
DSM_GRID_SPACING = p4dkey=gridDsmGridSpacing, type=int, min=1, max=1000, allowed_values=()
DSM_NOISE_FILTER = p4dkey=dsmFilterUseNoiseFilter, type=bool, allowed_values=()
DSM_XYZ_DELIMITER = p4dkey=gridDsmXYZDelim, type=str, allowed_values=(Space, Tab, Comma, Semicolon)
DTM_RESOLUTION = p4dkey=dtmResolution, type=float, max=10000.0, allowed_values=()
MOSAIC_NO_TRANSPARENCY = p4dkey=mosaicTIFFNoTransparency, type=bool, allowed_values=()
class pix4dengine.options.ExportOption

Options controlling which output files will be produced.

These options are described in a dedicated support page. Please look for the “p4dkey” reported here for each option.

class CameraCalibration

Camera calibration exports.

UNDISTORTED_IMAGES = p4dkey=exportUndistortedImages, type=bool, allowed_values=()
class Densification

Densification exports.

PCL_LAS = p4dkey=pclExportLAS, type=bool, allowed_values=()
PCL_LAZ = p4dkey=pclExportLAZ, type=bool, allowed_values=()
PCL_PLY = p4dkey=pclExportPLY, type=bool, allowed_values=()
PCL_XYZ = p4dkey=pclExportXYZ, type=bool, allowed_values=()
class Index

Index exports.

REFLECTANCE = p4dkey=indexReflectance, type=bool, allowed_values=()
REFLECTANCE_MERGED = p4dkey=indexReflectanceMergeTiles, type=bool, allowed_values=()
class Mesh

Mesh exports.

DXF = p4dkey=meshExportDXF, type=bool, allowed_values=()
FBX = p4dkey=meshExportFBX, type=bool, allowed_values=()
OBJ = p4dkey=meshExportOBJ, type=bool, allowed_values=()
PLY = p4dkey=meshExportPLY, type=bool, allowed_values=()
class Ortho

Orthomosaic exports.

CONTOUR_DXF = p4dkey=contourDXF, type=bool, allowed_values=()
CONTOUR_PDF = p4dkey=contourPDF, type=bool, allowed_values=()
CONTOUR_SHP = p4dkey=contourSHP, type=bool, allowed_values=()
DSM_GRID_LAS = p4dkey=gridDsmLAS, type=bool, allowed_values=()
DSM_GRID_LAZ = p4dkey=gridDsmLAZ, type=bool, allowed_values=()
DSM_TIFF = p4dkey=dsmTIFF, type=bool, allowed_values=()
DSM_TIFF_MERGED = p4dkey=dsmTIFFMergeTiles, type=bool, allowed_values=()
DSM_XYZ = p4dkey=gridDsmXYZ, type=bool, allowed_values=()
DTM_TIFF = p4dkey=dtmTIFF, type=bool, allowed_values=()
DTM_TIFF_MERGED = p4dkey=dtmTIFFMergeTiles, type=bool, allowed_values=()
MOSAIC_KML = p4dkey=mosaicKML, type=bool, allowed_values=()
MOSAIC_TIFF = p4dkey=mosaicTIFF, type=bool, allowed_values=()
MOSAIC_TIFF_MERGED = p4dkey=mosaicTIFFMergeTiles, type=bool, allowed_values=()
class pix4dengine.options.StandardExport

Options to access output files which are always produced during processing.

These options are described in a dedicated support page. Please look for the “p4dkey” reported here for each option.

class Calib

Calibration parameters.

BINGO = p4dkey=dummy_bingo, type=bool, allowed_values=(True)
CAMERA_POS = p4dkey=dummy_camerapos, type=bool, allowed_values=(True)
CAMERA_SSK = p4dkey=dummy_camerassk, type=bool, allowed_values=(True)
PHOTO_SSK = p4dkey=dummy_photossk, type=bool, allowed_values=(True)
class Report

Quality reports.

PDF = p4dkey=dummy_pdf, type=bool, allowed_values=(True)
XML = p4dkey=dummy_xml, type=bool, allowed_values=(True)

Finding output files

Interface to the output files of a project.

pix4dengine.exports.get_expected_output(project, *export_options)

Get a list of the expected output files related to an export option.

Parameters:
  • project (Project) – a Project object.
  • export_option – the target export option, whose output we want to collect. If "all" is passed instead, all the available output from the project configuration is returned.
Return type:

Mapping[Enum, str]

Returns:

A dictionary mapping an ExportOption or StandardExport to a path (str) pointing to the expected output file.

Note

The function does not check which files actually exist. For that purpose, use get_available_output().

Raises:
pix4dengine.exports.get_available_output(project, *export_options)

Get a list of available output files from an export option.

Parameters:
  • project (Project) – a Project object.
  • export_option – the target export option, whose output we want to collect. If "all" is passed instead, all the available output from the project configuration is returned.
Return type:

Mapping[Enum, Sequence[str]]

Returns:

A dictionary mapping a ExportOption or StandardExport to a list of paths (str) to the available output files. An empty list is returned if no file is found for that option.

Raises:
pix4dengine.exports.get_report(project)

Return a Report object from a Project instance.

Return type:Report
class pix4dengine.exports.Report(report_path)

Parser for the Pix4Dmapper quality report.

Parameters:report_path (str) – path to the report produced by Pix4Dmapper
absolute_geolocation_rms()

Return the absolute geolocation RMS.

Note

This is available only with Pix4Dmapper 4.3 or higher.

Raises:ReportParsingException – the version of the Pix4Dmapper is lower than 4.3.
Return type:GeolocationRMS
calibration_quality_status()

Returns the calibration quality status.

Return type:CalibrationQualityStatus
Returns:A CalibrationQualityStatus object.
camera_opt_rel_diff()

Returns the camera optimization relative difference.

Return type:float
gsd_in_cm()

Get the Ground Sampling Distance in cm.

Return type:float
gsd_in_inch()

Get the Ground Sampling Distance in inch.

Return type:float
image_dataset_info()

Return the image dataset information.

Return type:ImageDatasetInfo
Returns:An ImageDatasetInfo object.
keypoints_median_per_image()

Get the median number of keypoints per image.

Return type:int
matches_median_per_image()

Get the median number of matches per image.

Return type:int
exception pix4dengine.exports.ReportParsingException

Error while parsing the report from Pix4Dmapper.

exception pix4dengine.exports.OutputFilesNotFound

No export file is found where expected.

exception pix4dengine.exports.UnknownExportLocation

The expected path for an export is unknown.

exception pix4dengine.exports.UnsetExportException

The engine was configured not to produce the requested output file.

Quality report

Data structures used in the quality report parser.

class pix4dengine.utils.report.CalibrationQualityStatus

Container for the calibration quality status report.

Create new instance of CalibrationQualityStatus(images, dataset, camera_optimization, matching, georeferencing)

camera_optimization

Alias for field number 2

dataset

Alias for field number 1

georeferencing

Alias for field number 4

images

Alias for field number 0

matching

Alias for field number 3

class pix4dengine.utils.report.GeolocationRMS

Container for geolocation RMS.

Create new instance of GeolocationRMS(x, y, z)

x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

class pix4dengine.utils.report.ImageDatasetInfo

Container for the image dataset information.

Create new instance of ImageDatasetInfo(total, enabled, calibrated, calibrated_enabled, calibrated_percentage, disabled)

calibrated

Alias for field number 2

calibrated_enabled

Alias for field number 3

calibrated_percentage

Alias for field number 4

disabled

Alias for field number 5

enabled

Alias for field number 1

total

Alias for field number 0

class pix4dengine.utils.report.Quality

Quality enumeration for CalibrationQualityStatus.

Short status description for a quality item.

FAILURE = 'failure'
SUCCESS = 'success'
WARNING = 'warning'

Utilities

Settings

Settings for the pix4dmapper.

pix4dengine.settings.get_exe_path()

Get the path to the pix4dmapper or pix4dmapper.exe.

Return type:str
pix4dengine.settings.set_exe_path(path)

Store the path to the pix4dmapper or pix4dmapper.exe.

Parameters:path – the path to the executable to be used by default, e.g., by EngineWrapper instances.
Return type:None

Task system

Module for tasks and task runners.

class pix4dengine.task.Callbacks

Bundle of callbacks for a Task.

Defines functions to be called before execution, on successful execution, or in the event of an error.

Create new instance of Callbacks(on_start, on_success, on_error)

on_error

Alias for field number 2

on_start

Alias for field number 0

on_success

Alias for field number 1

class pix4dengine.task.Task(name, work, callbacks=Callbacks(on_start=<function Callbacks.<lambda>>, on_success=<function Callbacks.<lambda>>, on_error=<function Callbacks.<lambda>>))

Class representing a unit of work with associated call-backs.

Initialize a task with a name, work and optional call-backs.

Parameters:
  • name – the name of the task. Must be unique in the context in which it is being executed.
  • work – a callable object that does the work of the task.
  • callbacks – optional callback bundle with functions to execute before work is started, after work is finished without errors, or in the event of an error. Callbacks are defined via an instance of Callbacks.
name

The name identifying a task.

run()

Run the task.

Runs the on_start callbacks, the task’s work, followed by the on_success callbacks.

set_callbacks(callbacks)

Set the callbacks of this task.

class pix4dengine.task.TaskRunner

Class for storing and running a set of tasks with dependencies.

Initialize the TaskRunner as empty.

add_task(task, after=None, before=None)

Add a task to this runner.

Add a task to this runner, optionally specifying a relative ordering with resport to some tasks.

Parameters:
  • task – the task to be added
  • after – (optional) task should run after the task named after.
  • before – (optional) task should run before the task named before.

Note

before and after parameters define an interval. In other words, if requesting to run task B after task A and before C, B will run between A and C, but other tasks may run in between. For the sake of the example, the final sequence of tasks may, e.g., result in: A, D, E, B, F, C.

Raises:LookupErrorafter or before is not the name of a task registered in the runner.
get_task(name)

Get the task with a given name or raise py:exc:KeyError.

run()

Run all the tasks.

tasks

Iterable of tasks contained by the runner.

pix4dengine.task.run_tasks(tasks, global_callbacks=Callbacks(on_start=<function Callbacks.<lambda>>, on_success=<function Callbacks.<lambda>>, on_error=<function Callbacks.<lambda>>))

Run a sequence of tasks with optional callbacks.

Parameters:
  • tasks – a sequence of tasks to be executed.
  • global_callbacks – a set of callbacks to be applied to the ensemble of tasks.

GCP and mark definition

Data structures for working with GCP and marks.

class pix4dengine.utils.gcp.DefaultAccuracy

Default horizontal and vertical accuracy of 3D GCPs.

XY = 0.02
Z = 0.02
class pix4dengine.utils.gcp.GCP3D

3D Ground Control Point class.

To define a GCP, one must specify (lat, lon, alt), (x, y, z) or both. id and label must be unique within a project. xy_accuracy and z_accuracy are set to default values from DefaultAccuracy if omitted.

Example

GCP(label="gcp0", id=0, lat=3.14159, lon=9.51431, alt=42)

Parameters:
  • label – unique label of the GCP.
  • id – unique integer ID of the GCP.
  • x – x coordinate (map coordinates)
  • y – y coordinate (map coordinates)
  • z – z coordinate
  • lat – latitude
  • lon – longitude
  • alt – altitude
  • xy_accuracy – (x, y) accuracy
  • z_accuracy – z accuracy

Create new instance of GCP3D(label, id, x, y, z, lat, lon, alt, xy_accuracy, z_accuracy)

alt

Alias for field number 7

id

Alias for field number 1

label

Alias for field number 0

lat

Alias for field number 5

lon

Alias for field number 6

x

Alias for field number 2

xy_accuracy

Alias for field number 8

y

Alias for field number 3

z

Alias for field number 4

z_accuracy

Alias for field number 9

class pix4dengine.utils.gcp.Mark

Representation of a mark on an image.

Example

Mark(photo="DSC0001.JPG", x=300, y=200, scale=1.)

Parameters:
  • photo – file name of an image (the path is not needed)
  • x – x position of the GCP in the image (in pixels)
  • y – y position of the GCP in the image (in pixels)
  • scale – scale parameter

Create new instance of Mark(photo, x, y, scale)

photo

Alias for field number 0

scale

Alias for field number 3

x

Alias for field number 1

y

Alias for field number 2

Processing area

Utilities for defining a processing area.

The processing area can be defined manually in the Project, or a default definition can be inferred from the positions of calibrated cameras.

pix4dengine.utils.processingarea.get_proc_area_definition(project, buffer_width=30.0)

Get a default processing area definition from a calibrated project.

The default processing area is defined as the convex hull covering the positions of the calibrated images. A buffer region is added around this polygon.

Parameters:
  • project (Project) – the project from which we want to extract a processing area definition. The project must be calibrated beforehand.
  • buffer_width (float) – the width of the buffer region around the camera positions, in meters.
Return type:

List[PointXY]

Returns:

list of points defining the default processing area horizontally.

Raises:
  • ProcAreaDefinitionException – the file containing the information on the calibrated images positions cannot be parsed.
  • OutputFilesNotFound – the file with the calibrated positions cannot be found. This usually means that the project has not been yet calibrated.
pix4dengine.utils.processingarea.set_default_proc_area(project, buffer_width=30.0)

Set a default processing area in a project.

The default processing area is defined as the convex hull covering the positions of the calibrated images. A buffer region is added around this polygon.

Parameters:
  • project (Project) – the project for which the default processing area should be defined. The project must be calibrated beforehand.
  • buffer_width (float) – the width of the buffer region around the input points in meters.
Raises:
  • ProcAreaDefinitionException – the file containing the information on the calibrated images positions cannot be parsed.
  • OutputFilesNotFound – the file with the calibrated positions cannot be found. This usually means that the project has not been yet calibrated.
Return type:

None

Coordinate system constants

Constants used for the coordinate systems.

class pix4dengine.constants.coordsys.Geoid

Geoids available for setting the vertical coordinate system.

GEOID2008 = 'EGM 2008 Geoid'
GEOID84 = 'EGM 84 Geoid'
GEOID96 = 'EGM 96 Geoid'
class pix4dengine.constants.coordsys.ProjectCS

Enumeration of coordinate systems used in a project.

GCPS = 'Coordinate system used for the GCPs.'
IMAGES = 'Coordinate system used in the images.'
OUTPUT = 'Coordinate system used for the output files.'

Coordinate systems

Module with tools for working with different coordinate systems.

pix4dengine.coordsys.list_cs(search=None)

Returns a list of all available coordinate systems.

Parameters:search (Optional[str]) – if search is defined, only the coordinate systems containing such a string will be returned. The search is not case-sensitive.
Return type:List[str]
class pix4dengine.coordsys.CoordSys(project)

Class to access and modify the coordinate systems of a project.

The get_cs() and set_cs() of this class accepts an optional as_wkt argument set to False by default. If this parameter is True, all the methods return or accept a coordinate system in the Well-Known Text format. If False, they return or accept a projected coordinate system such as "Tokyo / Japan Plane Rectangular CS XIX". If as_wkt is False, all methods can raise a ValueError if the projected coordinate system can not be found in the software database.

Parameters:project – an instance of Project
get_cs(project_cs, as_wkt=False)

Get one of the project’s horizontal coordinate systems.

Parameters:
  • project_cs (ProjectCS) – an instance of ProjectCS defining which horizontal coordinate system to return
  • as_wkt (bool) – if True, the coordinate system is returned as WKT, otherwise it is returned as a projected CS
Return type:

str

get_vert_cs(project_cs)

Get one of the project’s vertical coordinate systems.

Parameters:project_cs (ProjectCS) – an instance of ProjectCS defining which horizontal coordinate system to return
Returns:if a float is returned, it is the height in meters above the WGS 84 ellipsoid. If a pix4dengine.constants.coordsys.Geoid instance is returned, it is the geoid in use. If None is returned, the coordinate system is arbitrary.
Return type:Three different object types can be returned
set_cs(project_cs, coord_sys, as_wkt=False)

Set one of the project’s horizontal coordinate systems.

Parameters:
  • project_cs (ProjectCS) – an instance of ProjectCS defining which horizontal coordinate system to return
  • as_wkt (bool) – if True, the coordinate system is returned as WKT, otherwise it is returned as a projected CS
Return type:

None

set_vert_cs(project_cs, coord_sys=None)

Set one of the project’s vertical coordinate systems.

Parameters:
  • project_cs (ProjectCS) – an instance of ProjectCS defining which horizontal coordinate system to return
  • coord_sys (Union[float, int, Geoid, None]) – if coord_sys is a float, the vertical coordinate system is set to be a geoid coord_sys meters above the WGS 84 ellipsoid. If coord_sys is a pix4dengine.constants.coordsys.Geoid, this geoid is directly used. If coord_sys is None, an arbitrary coordinate system is set.
pix4dengine.coordsys.proj_cs_to_wkt(proj_cs)

Returns a Well-Known Text (WKT) from a projected coordinate system.

Parameters:proj_cs (str) – projected coordinate system (e.g., "JGD2011 / Japan Plane Rectangular CS VIII")
Return type:str
Returns:WKT (e.g., 'PROJCS["JGD2011 / Japan Plane Rectangular CS VIII",GEOGCS["JGD2011"...')
Raises:ValueError when the coordinate system cannot be found.
pix4dengine.coordsys.wkt_to_proj_cs(wkt)

Returns a projected coordinate system from a Well-Known Text (WKT).

Parameters:WKT (e.g., 'PROJCS["JGD2011 / Japan Plane Rectangular CS VIII",GEOGCS["JGD2011"...') –
Returns:projected coordinate system (e.g., "JGD2011 / Japan Plane Rectangular CS VIII")
Return type:proj_cs
Raises:ValueError when the WKT cannot be found.

Project tools

Utilities for use with Project.

class pix4dengine.utils.project.MinMaxRange

Class to represent a range.

This can be used, e.g., for defining the vertical range of a project processing area. See processingarea.

Example

MinMaxRange(min=100, max=150.0)

Parameters:
  • min – minimum height (meters)
  • max – maximum height (meters)

Create new instance of MinMaxRange(min, max)

max

Alias for field number 1

min

Alias for field number 0

class pix4dengine.utils.project.PointXY

Class to represent a point in 2D space.

This can be used, e.g., for defining a project processing area horizontally. See processingarea.

Example

PointXY(x=153.2, y=201.24)

Parameters:
  • x – x position (map coordinates)
  • y – y position (map coordinates)

Create new instance of PointXY(x, y)

x

Alias for field number 0

y

Alias for field number 1

class pix4dengine.utils.project.Version

Three digits version information.

Create new instance of Version(major, minor, micro)

major

Alias for field number 0

micro

Alias for field number 2

minor

Alias for field number 1

Exceptions

Custom error classes raised by Pix4Dengine.

exception pix4dengine.utils.errors.FailedValidation(message=None)

Validation of the quality report failed, processing stopped.

exception pix4dengine.utils.errors.LoginError(error_msg='Default error message', pix4d_error_code='not found', stdout=None)

Failed authorizing to use Pix4Dmapper via the Pix4D licensing system.

exception pix4dengine.utils.errors.LogoutError(error_msg='Default error message', pix4d_error_code='not found', stdout=None)

Failed logging out of the Pix4D licensing system.

exception pix4dengine.utils.errors.ProcAreaDefinitionException(message=None)

Error while trying to automatically define a processing area.

exception pix4dengine.utils.errors.ProjectCreationError(error_msg='Default error message', pix4d_error_code='not found', stdout=None)

Creation of the project failed.

exception pix4dengine.utils.errors.ProjectOpeningError(message=None)

Opening of the project failed.

exception pix4dengine.utils.errors.ProjectProcessingError(error_msg='Default error message', pix4d_error_code='not found', stdout=None)

Processing of the project failed.

exception pix4dengine.utils.errors.ProjectSplittingError(message=None)

Splitting of the project failed.

exception pix4dengine.utils.errors.ReportingException(message=None)

Error while parsing STDOUT for reporting.

exception pix4dengine.utils.errors.SettingsError(message=None)

Failed reading or writing the Pix4Dengine settings.