Automarking quickstart¶

Prerequisites¶

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

Supported platforms are:

Ubuntu 18.04 64bit with Python 3.6
Windows 10 64bit with Python 3.8

Installation¶

Linux/Ubuntu 18.04¶

Before installing it, make sure that Python 3.6 (including pip) is installed.

It is installed system-wide by, e.g., running in a terminal:

sudo apt-get update
sudo apt-get install ./python3-automarking_0.6.4_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¶

Before installing it, make sure that Python 3.8 (including pip) is installed. Install Automarking by executing in a command interpreter:

pip install automarking_0.6.4-cp38-cp38m-win_amd64.whl

This will install Automarking system-wide and requires administrator privileges. The --user option can be added to install only for the current user. Alternatively, a Python virtual environment can also be used.

Basic usage of the Automarking module¶

Automarking can be used to generate a task to run in a Pix4Dengine SDK pipeline. In the example below, the code ensures that Pix4Dengine SDK is authorized to run, creates a project, sets up a fast-calibration pipeline, automatically marks GCPs on images, and finally runs a reoptimization step. The re-optimize step automatically uses the results of the Automarking task.

from pix4dengine import login_seat, create_project
from pix4dengine.pipeline import Pipeline, apply_template
from pix4dengine.pipeline.templates import RapidMaps3D
from pix4dengine.utils.gcp import GCP3D
from pix4dengine.constants.coordsys import ProjectCS
import automarking as am

# Define GCPs
gcps = [
    GCP3D(label="GCP_A", id=0, x=-88126.768, y=-129103.027, z=87.4669),
    GCP3D(label="GCP_B", id=1, x=-88135.258, y=-129137.575, z=87.4091),
    GCP3D(label="GCP_C", id=6, x=-88117.49, y=-129142.737, z=84.9376),
]

# Processing must be done inside a main program
if __name__ == "__main__":
    # Acquire the authorization to use Pix4Dengine
    login_seat(<email>, <pwd>)

    proj = create_project("test", image_dirs="/path/to/images/folder")

    # Make sure that output and GCP coordinate system are set correctly
    cs_name = "JGD2000 / Japan Plane Rectangular CS XIII"
    proj.coord_sys.set_cs_from_name(ProjectCS.GCPS, cs_name)
    proj.coord_sys.set_cs_from_name(ProjectCS.OUTPUT, cs_name)

    # Add GCPs
    proj.add_3d_gcps(gcps)

    # Create an automatic marking task with minimal configuration
    marker_task = am.make_task({am.Config.TARGET_DIAMETER: 70.0})

    # Define and run the calibration pipeline
    pipeline = Pipeline(algos=["CALIB", marker_task, "REOPT"])
    apply_template(pipeline, RapidMaps3D)
    pipeline.run(proj)

For more information about the Automarking task and its configuration, please refer to the API documentation.

AutoGCPs can be used with all control point (CP) types supported by the Pix4Dengine SDK. Checkpoints are, in particular, supported and can be used to evaluate the calibration uncertainty. Refer to the support pages and to the Pix4Dengine SDK documentation for further details.

Automarking report¶

After running, the CPMarker object provides access to a dictionary containing information that can be used to generate a quality report, summarising the results of the automatic image marking:

marker_task = am.make_task()

# Before running, the report is not available
assert marker_task.report is None

pipeline = Pipeline(project=project, algos=["CALIB", marker_task, "REOPT"])
pipeline.run()

# After running, the report dictionary is available
assert marker_task.report

Refer to report for details.

Known issues¶

As shown in the example above, CPs must be added to the project before running the CPMarker, because the task must have access to their coordinates. It is essential that the coordinate system of the CPs and of the project outputs are the same and that the chosen coordinate system is correct. Refer to the Pix4Dengine SDK documentation for details on how to choose and set coordinate systems.

Geographic coordinate systems (instead of projected ones) are not supported.

Currently, projects with highly variable ground sampling distance (GSD) are not well supported. Fewer correct detections may be obtained in projects where the GSD varies by a factor of more than 2-3 between different images.