Pix4D Automation Example

Description

Pix4D is a cloud based photogrammetry service that can generate orthophotos, point clouds and 3D models from aerial imagery. In the FME Hub are several transformers that allow you to connect to the Pix4DEngine online tools: https://hub.safe.com/?page=1&page_size=20&order=relevance&query=pix4d

In this example, we will use the FME Hub transformers and FME Server to create a process to completely automate the production of orthophotos, point clouds and 3D models from appropriate drone photography.

Requirements

To get good results, we will need imagery suitable for creating stereo models. Images should have 60% overlap along the flight lines, and 30% overlap between flight lines. Images should also include photo GPS centers in their EXIF tags.

We have a set of sample drone photos that can be used to test the process:

SampleImages.zip

Overview

We want the process to:

• Create a new Pix4D project

• Upload the photos to the project

• Start the Pix4D processing to create the orthophoto, point cloud and 3D model

• Wait for the processing to complete

• Zip up the results

• Provide the user with a download link for the results.

Pix4D provides a notification email when the process is finished, but only to the owner of the account, and this email cannot be changed, so we need to find another way to determine when the process is finished. The Pix4DProcessLauncher has an option to wait until the processing is finished, but we don’t want to waste an FME Engine waiting for a process that could take up to several hours for a larger project.

One solution is to check the project parameters with the Pix4DProjectInfoRetriever to see if the project status is set to DONE. Since we are implementing this on FME Server, the easiest way to do this is to create a Schedule to run a small workspace to check the progress every few minutes.

Once the process is finished, we can request a link to a zip file of the project outputs to send to the submitter. However, this zip file is not created until it is first requested, and it may take several minutes to create, so we will create another schedule to run a workspace to wait for the zip file to be finished.

Now we don’t want all these schedules cluttering up FME Server so we will also delete them when they are no longer needed. The easiest way to do this is to use FME Server’s REST API to create and remove schedules from within the workspaces themselves.

And so we end up with three workspaces:

• Pix4DAutomation

  • Uploads user images to FME Server

  • Creates new Pix4DEngine project

  • Uploads image to project

  • Launches Pix4D processing

  • Creates FME Server schedule to run checkPix4DProgress workspace every 5 minutes

  • Send ‘please wait’ HTML response to user

• checkPix4DProgress

  • Checks processing status

  • If process is finished:

    • Deletes the process checking schedule

    • Creates new schedule to run checkPix4DZip every 2 minutes

• checkPix4DZip

  • Requests project output zip url

  • If url is returned (zipping is done):

    • Deletes the zip checking schedule

    • Emails the user the zip file url

Once the workspace are uploaded to FME Server, we want to be able to run Pix4DAutomation without logging in to the FME Server interface. This is best done through FME 2019's FME Server Apps. For more detailed information please see Getting Started with FME Server Apps.

The workspaces can be downloaded from:

• Pix4DAutomation.fmw
• checkPix4DProgress.fmw
• checkPix4DZip.fmw

Workspaces

Pix4DAutomation

This workspace has JPEG reader to allow the user to upload images to FME Server, and an HTML writer to return the ‘please wait’ message while Pix4D processes the images.

It also requests the user’s email address to send a download link to.

Before using the workspace, you will need to set two private parameters:

FME Cloud token

Because the workspace will be creating and deleting schedules on the FME Server, it will need an authentication token to allow access to these functions. To generate this token, please follow these steps:

• Log into FME Server as an administrator

• From the User Settings icon in the upper right, choose Manage Tokens

• Click the New button to create a new token

• Give it a representative name (ie. Pix4D_Processs) and description

• Set a long expiration date (ie. 5 years)

• For simplicity, choose All Permissions

• Click OK to create the token

The token will be displayed. Copy and paste it into the FME Cloud Token parameter in the workspace. It might also be a good idea to download the token (using the Download button) and store it in a safe place, since this is the only time it can be seen, and it will be hidden in the workspace.

Pix4D Web Connection

When you register for your Pix4DEngine account, you will be given two access keys: a Client ID and Client Secret ID. Create a Pix4D Web Connection from these keys using the following steps:

• In Workbench, choose FME Options from the menu, then choose Web Connections.

• Click on the Manage Services button

• Choose Pix4DEngine from the list on the left and click the Download button

• Close the Manage dialog

• Click on the + to add a new web connection

• Set Web Service to Pix4DEngine

• Add a representative Connection Name (ie. My Pix4D Connection)

• Add the Client ID and Client Secret ID onto the appropriate boxes

• Click Authenticate to test and save

Set the workspace Pix4D Web Connection parameter to the new connection.

Workspace details

The first section reads the JPEG images uploaded to FME Server, but discards the geometry, so that only the headers are read. These are aggregated into a single trigger feature, to which the source files and workspace folder are added as attributes.

The JPEG reader is not really used, but is just included to enable the image upload section in the FME Server interface.

The DatetimeStamper and AttributeRounder create a timestamp used to provide a unique name for each project within the Pix4DProjectCreator

The Pix4DConnection from the private parameter is used to connect to the Pix4D service.

The Pix4DCreator will return the Pix4D project id number in the attribute proj_id.

The Pix4DImageAdder uses the proj_id attribute and the list of source images to upload them to Pix4D and register them with the project.

The Pix4DProcessLauncher starts the processing, without waiting for the results.

All three workspaces should be uploaded to the same repository on FME Server, but we don’t know what it’s called. However, we can extract the repository name from the workspace path, to use when creating the schedule for the polling workspaces.

Next, we create a schedule to run the polling workspace.

This submits a REST API call to the local FME server to create a new schedule, using the FME Server token in the private parameter.

The Pix4D project id number and user email are passed along to the polling workspace as input parameters. The schedule is given a very long end date, since it will be deleted by the process instead. The interval is set to every 5 minutes. The project number is used to create a unique name for each schedule, allowing more than one process to be run concurrently.

Finally, we create a simple HTML response to be returned to the user to let them know that the job was successfully submitted. This workspace should be published to the Data Streaming Service, so that the HTML output is seamlessly streamed back to the user.

checkPix4DProgress

This workspace is run at intervals to check whether the Pix4D process is finished.

Like in the automation workspace, the FME Server token and Pix4D connection must be set up in the Private parameters before publishing to FME Server. The workspace should be published to the Job Submitter service.

Workspace details

A Pix4DProjectInfoRetriever transformer is used to get the current project info, then the project status is check to see if the value is ‘DONE’.

If the processing is complete, a REST API call is made to FME Server to delete the schedule currently running the check progress workspace,

Next, another REST API call to FME Server is made to create a new schedule to run the zip checking workspace every two minutes.

The schedule is also supplied with the project number and user email, which it will provide to the zip checking workspace.

checkPix4DZip

This workspace requests the zip file location for the Pix4D output files. This zip file is not created during processing, so the first run of the workspace will kick off the zip process.

The workspace will require that the FME Server token and Pix4D web connection be set as well.

Email setup

The Emailer transformer currently uses a GMail connection that needs to be set up for your GMail account.

Pick the Add Web connection option, then choose Google GMail.

Click the Authenticate button to log into GMail and authenticate the connection. This only needs to be done once per machine.

This Web Connection will be uploaded to FME Cloud when you publish the workspace. The workspace should be published to the Job Submitter service.

Workspace details

The Pix4DOutputFetcher transformer is used to request the zip file location. If the zipping is finished and the location is returned, a REST API call to FME Server is made to delete the zip checking schedule, then an email is sent to the user provided address with the url of the zip file. The Body of the email can be modified to provide a richer message to the user.

Conclusion

This example is meant to familiarize you with the capabilities of the Pix4DEngine service, and to show you how they can be accessed through the FME Hub Pix4D transformers.

We hope you will use this as a starting point for your own automated Pix4D processes.