Tutorial #A01 : how to manage control points and distances in 3DF Zephyr

Using control points and distances


Welcome to the 3DF Zephyr tutorial series.
In this recipe, you will learn how to use control points and distances with 3DF Zephyr.
This tutorial cannot be completed with 3DF Zephyr evaluation.
This tutorial is not about reconstruction: if you are not interested in geographical analysis and survey you can probably skip this tutorial.


  • Step 1 – Introduction

Control points allow you to define a specific coordinate. That coordinate can then be used to calculate the distance between other points and cameras, as well as a constraint for alignment.
Please remember that any reconstruction is up to an arbitrary scale factor, a translation and a rotation. In this section will be explained how to define a global scale factor to perform measurements and align the world position, scale and rotation with user defined control points, as well as measure distances.
To complete this tutorial, you can either use your own dataset, create the reconstruction starting from our dataset or directly download the .zep project file used in this recipe.
Special thanks to airmap for sharing this dataset!

download datasetDownload Dataset – University of Udine Zip (77.3MB)
downloadDownload Dataset – University of Udine .Zep (487MB)

Either create your own reconstruction or use our low resolution zep file. This is enough to understand control points.

  • Step 2 – Adding control points by picking

The easiest (yet the less accurate) way to add a control point is by picking it directly from the 3D reconstruction.

In the “GCP” Panel click the “Pick Control Point” Button (1). Your mouse cursor will turn into a crosshair icon: hover the crosshair on the scene (2) and then left click on the desired position. A new control point will appear in the Control Point List (3).

That’s all you need to do to pick a control point!


  • Step 3 – Adding control points by picking on photos

A much more accurate way to add control point is to pick them directly from the photos. You need to pick the same coordinate on at least two pictures in order to triangulate and make zephyr calculate the control points.
Lets clear the previously created control points by right clicking on the Point List (4) and left clicking on “remove all”. Click Yes to confirm.

Now, from the “GCP” Panel (1) click “Pick Control Point (From images)” (5): the “Control Point Picker window” (6) will appear. From the “Camera List” (7) left click a picture to view it in the “Control Point Picker Selector” (8). Left click where you want the control point to appear and a red dot (9) will appear. The “Ok button” (10) won’t be clickable yet: remember, we need at least two images to define a control point in the 3D world.

Click again on another picture from the “Camera List” (7): this time you’ll also see an epipolar line (11) that will help you select your second coordinate (12) by left clicking as you did for the first one. The “OK button” (10) will now be clickable – add as many coordinates as you want (the more coordinates, the more accurate the control point will be) and then click OK to finish adding your control point.

  • Step 4 – Importing control points from a text file

Clear all the created control points as you did in the previous step.

Importing control points from text files allows you to easily batch import control points from other applications: right click this link and “save as” this sample text file as 3DF_Zephyr_Tutorial_02_2D_coords.txt

To import control points from a text file, simply click on the “Import control points” Button (13) and then “Browse” (14) and select the sample text file “3DF_Zephyr_Tutorial_02_2D_coords.txt” (15) and then click “Open” (16). At last, confirm by pressing “Import 2D Coordinates” (17) button.

A dialog screen should pop up: this notice should tell you that the import phase has been done correctly. Click OK.

Protip:  For each control point to be imported, you need to specify at least two 2D images coordinates. For example, to import a control point called “Point1” that is seen by the camera generated from the picture named “PictureA.JPG” at coordinates (x,y) 100,600 and from a second camera, generated from the picture named “PictureB.JPG” at coordinates (200,660) your import file should be formatted like this
Point1 PictureA.JPG 100 600
Point1 PictureB.JPG 200 660

  • Step 5 – Aligning the world to control points

Since the reconstruction is up to an arbitrary scale, rotation and translation, you might want to fix that by setting constraints to the world. This is easily done by clicking the “Align world to control points” Button.

· using 1 control point will translate the world
· using 2 control points will translate the world and set a global scale
· using 3 or more control points will set a full transformation that will scale, translate and rotate the world.

You can either import the constraints from files with the “Import Constraints from file” button (18) or you manually can set control points. Note that each point can be selected as Control Point, Constraint, or even as both by selecting the appropriate checkbox in the “constraint/control point selector” (19).

It’s usually a good idea to also include control points that are not constraints.

You can also perform a bundle adjustment operation by checking “Perform Bundle Adjustment” (20).

Simply click “OK” when ready to proceed.

You can experiment a bit with the manual settings, or right click this link and save 3DF_Zephyr_Tutorial_02_3D_coords.txt – similarly to the previous step, click the “Import Constraints from file” Button (18), browse and select 3DF_Zephyr_Tutorial_02_3D_coords.txt and then click “Open”.

Protip: in a similar fashion to the control points import file format, the constraint file formats requires each line to be formatted with name x y z. If you take a closer look to the file you just downloaded, you’ll notice a star before some control points. If you try the import phase, you’ll see that those points will be ignored, because the control point name must be identical to the one defined in the zephyr workspace. It is also possible to set camera constraints by right clicking and selecting “add camera constraint”.

  • Step 6 – Measurements

Control distances can be defined as the distance between two control points, the distance between a control point and a camera, or the distance between two cameras. With 3DF Zephyr you can easily define control distances and even scale the world with control distances.

Click on the “Add Control Distance” Button (21). The “control point selection window” (22) will pop up. From this window, pick the two control points needed from the Control Point #1 selection menu (23) and the Control Point #2 selection menu (24). This example shows two control points, but they can be cameras as well. Once you click “OK” (25), the distance will be drawn as a green line (26) and rendered onto the screen (in this case, 30.3164).

The control points used and the distance will also appear in the Control Distance List (27).

You can scale the world using control distances; to do so, simply click on the Scale World with Control Distances Button (28):  in the window that will appear, set the previously created control distance(s) and set the desired distance value. Click OK and you’re done!

If a mesh is available in the workspace, you can measure its volume or its area by using the “Measure mesh volume button” (29) and the “Measure mesh area button” (30).

As an additional tool, you can quickly measure angles between control points from the “Tools > Control Points and Distances > Compute The Angle between three points” menu.


  • Final notes

Control points and control distances are a powerful and easy tool that can save you a lot of time. Learning to import control points and constraints from file is probably worth investing a few minutes of your time since they can greatly improve your workflow process speed.

The next tutorial is about orthophoto generation. Click here to proceed to tutorial #3.