There are two methods for running with docker. One pulls a pre-built image from the docker hub. This is the most reliable. You can also :ref:`build your own image <docker-installation>`. In either case, the run command is the same, what you will change is the name of the image. For the docker hub image, use ``opendronemap/odm``. For an image you built yourself, use that image name (in our case, ``my_odm_image``).::
Where /my/project is the path to your project containing an ``images`` folder (/my/project/images). ``-v`` is used to connect folders in the docker container to local folders. See :doc:`outputs` for reference on the project layout.
* The header line is a description of a UTM coordinate system, which must be written as a proj4 string. http://spatialreference.org/ is a good resource for finding that information. Please note that currently angular coordinates (like lat/lon) DO NOT work.
* Subsequent lines are the X, Y & Z coordinates, your associated pixels and the image filename:
If you supply a GCP file called gcp_list.txt then ODM will automatically detect it. If it has another name you can specify using ``--gcp <path>``. If you have a gcp file and want to do georeferencing with exif instead, then you can specify ``--use-exif``.
`This post has some information about placing Ground Control Targets before a flight <http://diydrones.com/profiles/blogs/ground-control-points-gcps-for-aerial-photography>`_, but if you already have images, you can find your own points in the images post facto. It's important that you find high-contrast objects that are found in **at least** 3 photos, and that you find a minimum of 5 objects.
Sharp corners are good picks for GCPs. You should also place/find the GCPs evenly around your survey area.
The ``gcp_list.txt`` file must be created in the base of your project folder.
Below you will find step-by-step instructions for some common use cases.
Creating High Quality Orthophotos
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Without any parameter tweaks, ODM chooses a good compromise between quality, speed and memory usage. If you want to get higher quality results, you need to tweak some parameters:
*``--ignore-gsd`` is a flag that instructs ODM to skip certain memory and speed optimizations that directly affect the orthophoto. Using this flag will increase runtime and memory usage, but will produce sharper results.
*``--texturing-nadir-weight`` should be increased to ``29-32`` in urban areas to reconstruct better edges of roofs. It should be decreased to ``0-6`` in grassy / flat areas.
*``--texturing-data-term`` should be set to `area` in forest areas.
*``--mesh-size`` should be increased to `300000-600000` and `--mesh-octree-depth`` should be increased to `10-11` in urban areas to recreate better buildings / roofs.
Creating Digital Terrain Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default ODM does not create DEMs. To create a digital terrain model, make sure to pass the ``--dtm`` flag.
For DTM generation, a Simple Morphological Filter (smrf) is used to classify points in ground vs. non-ground and only the ground points are used. The ``smrf`` filter can be controlled via several parameters:
*``--smrf-scalar`` scaling value. Increase this parameter for terrains with lots of height variation.
*``--smrf-slope`` slope parameter, which is a measure of "slope tolerance". Increase this parameter for terrains with lots of height variation. Should be set to something higher than 0.1 and not higher than 1.2.
*``--smrf-threshold`` elevation threshold. Set this parameter to the minimum height (in meters) that you expect non-ground objects to be.
*``--smrf-window`` window radius parameter (in meters) that corresponds to the size of the largest feature (building, trees, etc.) to be removed. Should be set to a value higher than 10.
Changing these options can affect the result of DTMs significantly. The best source to read to understand how the parameters affect the output is to read the original paper `An improved simple morphological filter for the terrain classification of airborne LIDAR data <https://www.researchgate.net/publication/258333806_An_Improved_Simple_Morphological_Filter_for_the_Terrain_Classification_of_Airborne_LIDAR_Data>`_ (PDF freely available).
Overall the ``--smrf-threshold`` option has the biggest impact on results.
SMRF is good at avoiding Type I errors (small number of ground points mistakenly classified as non-ground) but only "acceptable" at avoiding Type II errors (large number non-ground points mistakenly classified as ground). This needs to be taken in consideration when generating DTMs that are meant to be used visually, since objects mistaken for ground look like artifacts in the final DTM.
Two other important parameters affect DEM generation:
*``--dem-resolution`` which sets the output resolution of the DEM raster (cm/pixel)
*``--dem-gapfill-steps`` which determines the number of progressive DEM layers to use. For urban scenes increasing this value to `4-5` can help produce better interpolation results in the areas that are left empty by the SMRF filter.
The SLAM algorithm requires the camera to be calibrated. It is difficult to extract calibration parameters from the video's metadata as we do when using still images. Thus, it is required to run a calibration procedure that will compute the calibration from a video of a checkerboard.
We will start by **recording the calibration video**. Display this `chessboard pattern <https://dl.dropboxusercontent.com/u/2801164/odm/chessboard.pdf>`_ on a large screen, or `print it on a large paper and stick it on a flat surface <http://www.instructables.com/id/How-to-make-a-camera-calibration-pattern/>`_. Now record a video pointing the camera to the chessboard.
While recording move the camera to both sides and up and down always maintaining the entire pattern framed. The goal is to capture the pattern from different points of views.
Now you can **run the calibration script** as follows::
You will see a window displaying the video and the detected corners. When it finish, it will print the computed calibration parameters. They should look like this (with different values)::
# Camera calibration and distortion parameters (OpenCV)
Camera.fx: 1512.91332401
Camera.fy: 1512.04223185
Camera.cx: 956.585155225
Camera.cy: 527.321715394
Camera.k1: 0.140581949184
Camera.k2: -0.292250537695
Camera.p1: 0.000188785464717
Camera.p2: 0.000611510377372
Camera.k3: 0.181424769625
Keep this text. We will use it on the next section.
