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:	`ValueError` – `proj_name` is invalid (a p4d file or a path given). `FileExistsError` – the project already exists. Use `open_project()` to open an existing project. `FileNotFoundError` – `images_dir` is not a directory or does not exist. `TypeError` – `template` or `external_geoloc` has the wrong type.

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:	`ProjectOpeningError` – the project p4d file cannot be found `ValueError` – the given `proj_name` is invalid (p4d file or a path)

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:	`ProjectProcessingError` – processing failed. `FileNotFoundError` – the project to be processed could not be found. `FailedValidation` – `validator` returned `False`.
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:	`ValueError` – `proj_name` is invalid (a p4d file or a path given). `FileExistsError` – a project with `proj_name` exists already. Use `open_project()` to open an existing project. `FileNotFoundError` – `images_dir` is not a directory or does not exist. `TypeError` – `template` or `external_geoloc` has the wrong type.
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:

To open an existing project use open_project().
To create a new project use create_project().
To split an existing project use create_split_projects().

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:	`TypeError` – if the `export_option` type is not an `Enum` or the string `"all"`. `UnknownExportLocation` – if the requested export option is not recognised. `UnsetExportException` – if the requested export option is set to False.

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:	`TypeError` – if the `export_option` type is not an `Enum` or the string `"all"`. `UnknownExportLocation` – if the requested export option is not recognised. `UnsetExportException` – if the requested export option is set to False.

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:	`LookupError` – `after` 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.