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 tutorial, you will learn how to use control points and control distances with 3DF Zephyr.
This tutorial cannot be completed with 3DF Zephy Free or Lite versions. It is not about 3D reconstruction: you can probably skip this tutorial if you are not interested in geographical analysis and survey.


  • 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, and a constraint for alignment.

Remember that any reconstruction is up to an arbitrary scale factor, a translation, and a rotation!

The following guide will explain 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 to measure distances.

Control points, alignment and model scaling with known control points (or known distances) can be managed from the panel on the right labeled “GCP” (Ground Control Points).


To complete this tutorial, you can either use your 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)

  • Adding control points by direct picking

The easiest (yet the less accurate) way to add a control point is by picking it directly from the 3D reconstruction (on a point cloud or a mesh, but not on a textured mesh).

In the “GCP” Panel, click the “Pick Control Point” Button (1). Your mouse cursor will turn into a crosshair icon: move 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!


  • Adding control points by picking on photos

A 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 the 3D coordinates and make Zephyr calculate the control points.

Let’s remove the previously created control points by right-clicking on the Point List (3) and left clicking on “remove all”. Click Yes to confirm.

Now, from the “GCP” Panel click “From images” button (4) to pick the Control Points: the “Control Point Picker window” (5) will appear.

From the “Camera List” (6) left click a picture to view it in the “Control Point Picker Selector” (7). Left click where you want the control point to appear and a red dot (8) will appear. The “Ok” button (9) won’t be clickable yet:
Remember, we need at least two images to define a control point in the 3D world!
The Advanced Tools can provide valuable help with control point placement:

Advanced Tools
The following functions will help to place control points on images in the control point editing window:

Fit in view: resize the image to fit in the view.


Rotate 90 degrees clockwise, counter-clockwise, reset rotation: rotate the image and reset the initial position.


Show magnifier: show/hide the magnifier on the cursor while placing control points on images.


Show reprojection error: show/hide the current control point’s local and global reprojection errors.


Show epipolar line: show/hide the epipolar line.


Show other points: show/hide previously placed control points.


Automatic matching on current image: find and place a control point on the current image automatically.


Automatic matching on all images: find and place a control point on all the pictures automatically.


Detect marker: It automatically detects the center of a rectangular marker placed in the scene. By clicking the “Detect marker” icon and drawing a rectangle upon the center of the marker you want to be found, 3DF Zephyr will automatically place the control point at the center.

Note: Using the tool with a check-board style marker will improve the automatic detection.
Detect sphere: it allows detecting the center of the spheres placed in the scene. By clicking on the “Detect sphere'” icon and drawing a rectangle over the sphere you want to be found in the image, 3DF Zephyr will automatically place the control point at the center.
Note: This feature is expressly designed for the forensics industry, i.e., to support the analysis of the line of fire in crime scenes where a laser scanner scans the spheres on the trajectory rod.

Clear point: remove control points placed on the image.


Click again on another picture from the “Camera List” (6): this time you’ll also see an epipolar line (10) that will help you select your second coordinate (11) by left clicking as you did for the first one. The “OK” (9) button 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. When changing the 2D position’s coordinate on the immage, you can see in real-time the Global Reprojection error and the Local Reprojection error.

*TIP* Camera Visibility (Click here)
You can change the camera “Visibility” by selecting the “Show reprojection cameras” option from the drop-down menu in the bottom left corner of the editing window. That allows you to place the control points on “far cameras” (dull yellow frames) as well. In some cases, this method could improve the orientation accuracy, especially when a few cameras have a high reprojection error. “Show picked cameras” option display those cameras (green frames) where the control point is already placed.

  • Importing control points from a text file

    Importing 2D control points from a text file


2D coordinates are the X and Y coordinates of a point in an image.

2D coordinates are meant to speed up the control points import in a certain project (e.g., if you are running a second test on a dataset you have already processed, you can easily export 2D coordinates from the previous project and instantly load them into the current one): right-click [THIS LINK] and “save as” this sample text file as 3DF_Zephyr_Tutorial_02_2D_coords.txt

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

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

*TIP* 2D coordinates file formats (Click here)
For each control point to be imported, you need to specify at least two 2D 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

    Importing 3D control points from a text file

A 3D coordinate is an X;Y;Z coordinate located into the 3D space, such as the 3DF Zephyr rendering window.

For importing 3D control points from a file, click on “Import 3D” button (12a).
Search and select the 3D control points file by clicking on the “Browse” button (13a), and click the “OK” button (14a).
The 3D control points will be added in the rendering window and in the GCP panel on the right.


  • Scaling the model with 3D constraints

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 model with 3D constraints” 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 set the constraints, by importing the coordinates from an external file, with the “Import Constraints from file” (17) button or you can manually set them by clicking on the box of each point. Note that each point can be selected as Check Point, Constraint, or even as both by selecting the appropriate checkbox in the “constraint/checkpoint selector”(18).


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

*TIP* Difference between Constraints and Check points (Click here)
Constraints are those points you are most confident of in terms of accuracy level, and 3DF Zephyr relies on them to drive the scaling process.
Check points are references that the software only considers while scaling to keep the error value monitored.

You can experiment a bit with the import and manual settings, by right click [THIS LINK] and “save3DF_Zephyr_Tutorial_02_3D_coords.txt (19) (similarly to the previous step), click the “Import Constraints from file” (17) Button, browse and select 3DF_Zephyr_Tutorial_02_3D_coords.txt and then click “Open”.

*TIP* Control points import file format (Click here)
The control points (coordinates) file format, requires each line to be formatted as follows: label name x y z or label name, x, y, z.
If you take a closer look at the file you just downloaded, you’ll notice a star (*) before some constraints. If you try to import them, you will see that those points will be ignored as the coordinates you are importing and the GCPs you defined in the 3DF Zephyr workspace must have the same names/labels. It is also possible to set camera constraints by right-clicking and selecting “add camera constraint“.

Point4 361856.6827 5104563.954 117.631000
*Point5 361858.8289 5104620.249 117.501400

In the “Coordinate Reference System section”, it is possible to change both the input / target reference system, and the Geoid Gravity Model.

*TIP* Change Reference System and Geoid Model (Click here)

Click the “Select Projection CS” option to open the 3DF Zephyr coordinate system database:

The Projection Coordinates System window will open:

Select the correct coordinate system from the 3DF Zephyr database, or import a new one from an external source by clicking the “Import” button. Optionally, a Geoid Gravity Model can be loaded as well, in relation to the Coordinate Reference System. This feature can be helpful if you have taken GPS coordinates in a different reference system, which will cause a wide metric error compared to the GPS coordinates obtained from the pictures.

Simply click “Trasform and check errors” (20) button when you ready to proceed.


Note: You can also perform a Bundle Adjustment algorithm by checking “Perform Bundle Adjustment” check box.

The Bundle Adjustment adjusts the cameras orientations and position by minimizing the reprojection error of the placed control points.
For more details see the tutorial dedicated to the Bundle Adjustment.


  • Scaling using distances

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 “Distance” Button (21), in the “Measures” tab. 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 (Point 1 and Point 3), 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, 31.0013).

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


To Scale the world using control distances; simply click on the “Scale World with Control Distances” Button (28) in the Measures panel, and the “Scale with know distances” (29) window will appear. You can flag the previously created control distance(s) as Constraint and Check (30) as before with the Control points. Activating the flags will set the desired “Distance value” (31) for scaling the points cloud or the mesh. For example, you can set it to 20.000 meters, and click the “OK” button (32). You’re done! The whole mesh will be scaled on the newly inserted value.


  • Final notes

Control points and control distances are powerful and easy tools that can save you a lot of time. Learning to import control points and constraints from files 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.