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 build your own image. 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 Outputs for reference on the project layout.

To pass in custom parameters to the run.py script, simply pass it as arguments to the docker run command. For example:

First thing you need to do is set the project path. Edit the settings.yaml file to add your projects folder:

# This line is really important to set up properlyproject_path:''# Example: '/home/user/ODMProjects'# The rest of the settings will default to the values set unless you uncomment and change them#resize_to: 2400

You must change project_path:'' to add an absolute path to somewhere on your machine. Whenever you run a new project, it will be saved here.

To use OpenDroneMap run the following command:

pythonrun.py--images</path/to/images>[arguments]<project-name>

Then sit back, grab a coffee and wait. You only have to specify --images</path/to/images> on the first run.

-h,--helpshowthishelpmessageandexit--images<path>,-i<path>Pathtoinputimages--project-path<path>Pathtotheprojectfolder--resize-to<integer>resizesimagesbythelargestsideforopensfm.Setto-1todisable.Default:2048--end-with<string>,-e<string>Canbeoneof:dataset|split|merge|opensfm|mve|odm_filterpoints|odm_meshing|mvs_texturing|odm_georeferencing|odm_dem|odm_orthophoto--rerun<string>,-r<string>Canbeoneof:dataset|split|merge|opensfm|mve|odm_filterpoints|odm_meshing|mvs_texturing|odm_georeferencing|odm_dem|odm_orthophoto--rerun-allforcererunofalltasks--rerun-from<string>Canbeoneof:dataset|split|merge|opensfm|mve|odm_filterpoints|odm_meshing|mvs_texturing|odm_georeferencing|odm_dem|odm_orthophoto--video<string>Pathtothevideofiletoprocess--slam-config<string>Pathtoconfigfilefororb-slam--proj<PROJ4string>Projectionusedtotransformthemodelintogeographiccoordinates--min-num-features<integer>Minimumnumberoffeaturestoextractperimage.Morefeaturesleadstobetterresultsbutslowerexecution.Default:8000--matcher-neighbors<integer>Numberofnearestimagestopre-matchbasedonGPSexifdata.Setto0toskippre-matching.NeighborsworkstogetherwithDistanceparameter,setbothto0tonotusepre-matching.OpenSFMusesbothparametersatthesametime,Bundlerusesonlyonewhichhasvalue,preferingtheNeighborsparameter.Default:8--matcher-distance<integer>Distancethresholdinmeterstofindpre-matchingimagesbasedonGPSexifdata.Setbothmatcher-neighborsandthisto0toskippre-matching.Default:0--use-fixed-camera-paramsTurnoffcameraparameteroptimizationduringbundler--max-concurrency<positiveinteger>Themaximumnumberofprocessestouseinvariousprocesses.Peakmemoryrequirementis~1GBperthreadand2megapixelimageresolution.Default:4--depthmap-resolution<positivefloat>Controlsthedensityofthepointcloudbysettingtheresolutionofthedepthmapimages.Highervaluestakelongertocomputebutproducedenserpointclouds.Default:640--opensfm-depthmap-min-consistent-views<integer:2<=x<=9>Minimumnumberofviewsthatshouldreconstructapointforittobevalid.Uselowervaluesifyourimageshavelessoverlap.Lowervaluesresultindenserpointcloudsbutwithmorenoise.Default:3--opensfm-depthmap-method<string>Rawdepthmapcomputationalgorithm.PATCH_MATCHandPATCH_MATCH_SAMPLEarefaster,butmightmisssomevalidpoints.BRUTE_FORCEtakeslongerbutproducesdenserreconstructions.Default:PATCH_MATCH--opensfm-depthmap-min-patch-sd<positivefloat>WhenusingPATCH_MATCHorPATCH_MATCH_SAMPLE,controlsthestandarddeviationthresholdtoincludepatches.Patcheswithlowerstandarddeviationareignored.Default:1--use-hybrid-bundle-adjustmentRunlocalbundleadjustmentforeveryimageaddedtothereconstructionandaglobaladjustmentevery100images.Speedsupreconstructionforverylargedatasets.--mve-confidence<float:0<=x<=1>Discardpointsthathavelessthanacertainconfidencethreshold.ThisonlyaffectsdensereconstructionsperformedwithMVE.Highervaluesdiscardmorepoints.Default:0.6--use-3dmeshUseafull3Dmeshtocomputetheorthophotoinsteadofa2.5Dmesh.Thisoptionisabitfasterandprovidessimilarresultsinplanarareas.--skip-3dmodelSkipgenerationofafull3Dmodel.Thiscansavetimeifyouonlyneed2DresultssuchasorthophotosandDEMs.--use-opensfm-denseUseopensfmtocomputedensepointcloudalternatively--ignore-gsdIgnoreGroundSamplingDistance(GSD).GSDcapsthemaximumresolutionofimageoutputsandresizesimageswhennecessary,resultinginfasterprocessingandlowermemoryusage.SinceGSDisanestimate,sometimesignoringitcanresultinslightlybetterimageoutputquality.--mesh-size<positiveinteger>Themaximumvertexcountoftheoutputmesh.Default:100000--mesh-octree-depth<positiveinteger>Oct-treedepthusedinthemeshreconstruction,increasetogetmorevertices,recommendedvaluesare8-12.Default:9--mesh-samples<float>=1.0>Numberofpointsperoctreenode,recommendedanddefaultvalue:1.0--mesh-point-weight<positivefloat>ThisfloatingpointvaluespecifiestheimportancethatinterpolationofthepointsamplesisgivenintheformulationofthescreenedPoissonequation.Theresultsoftheoriginal(unscreened)PoissonReconstructioncanbeobtainedbysettingthisvalueto0.Default=4--fast-orthophotoSkipsdensereconstructionand3Dmodelgeneration.Itgeneratesanorthophotodirectlyfromthesparsereconstruction.Ifyoujustneedanorthophotoanddonotneedafull3Dmodel,turnonthisoption.Experimental.--crop<positivefloat>Automaticallycropimageoutputsbycreatingasmoothbufferaroundthedatasetboundaries,shrinkedbyNmeters.Use0todisablecropping.Default:3--pc-classifyClassifythepointcloudoutputsusingaSimpleMorphologicalFilter.Youcancontrolthebehaviorofthisoptionbytweakingthe--dem-*parameters.Default:False--pc-csvExportthegeoreferencedpointcloudinCSVformat.Default:False--pc-lasExportthegeoreferencedpointcloudinLASformat.Default:False--pc-filter<positivefloat>FiltersthepointcloudbyremovingpointsthatdeviatemorethanNstandarddeviationsfromthelocalmean.Setto0todisablefiltering.Default:2.5--smrf-scalar<positivefloat>SimpleMorphologicalFilterelevationscalarparameter.Default:1.25--smrf-slope<positivefloat>SimpleMorphologicalFilterslopeparameter(riseoverrun).Default:0.15--smrf-threshold<positivefloat>SimpleMorphologicalFilterelevationthresholdparameter(meters).Default:0.5--smrf-window<positivefloat>SimpleMorphologicalFilterwindowradiusparameter(meters).Default:18.0--texturing-data-term<string>Dataterm:[area,gmi].Default:gmi--texturing-nadir-weight<integer:0<=x<=32>Affectsorthophotosonly.Highervaluesresultinsharpercorners,butcanaffectcolordistributionandblurriness.Uselowervaluesforplanarareasandhighervaluesforurbanareas.Thedefaultvalueworkswellformostscenarios.Default:16--texturing-outlier-removal-type<string>Typeofphotometricoutlierremovalmethod:[none,gauss_damping,gauss_clamping].Default:gauss_clamping--texturing-skip-visibility-testSkipgeometricvisibilitytest.Default:False--texturing-skip-global-seam-levelingSkipglobalseamleveling.UsefulforIRdata.Default:False--texturing-skip-local-seam-levelingSkiplocalseamblending.Default:False--texturing-skip-hole-fillingSkipfillingofholesinthemesh.Default:False--texturing-keep-unseen-facesKeepfacesinthemeshthatarenotseeninanycamera.Default:False--texturing-tone-mapping<string>Turnongammatonemappingornonefornotonemapping.Choicesare'gamma'or'none'.Default:none--gcp<pathstring>pathtothefilecontainingthegroundcontrolpointsusedforgeoreferencing.Default:None.Thefileneedstobeonthefollowinglineformat:eastingnorthingheightpixelrowpixelcolimagename--use-exifUsethistagifyouhaveagcp_list.txtbutwanttousetheexifgeotagsinstead--dtmUsethistagtobuildaDTM(DigitalTerrainModel,groundonly)usingasimplemorphologicalfilter.Checkthe--dem*and--smrf*parametersforfinertuning.--dsmUsethistagtobuildaDSM(DigitalSurfaceModel,ground+objects)usingaprogressivemorphologicalfilter.Checkthe--dem*parametersforfinertuning.--dem-gapfill-steps<positiveinteger>Numberofstepsusedtofillareaswithgaps.Setto0todisablegapfilling.Startingwitharadiusequaltotheoutputresolution,NdifferentDEMsaregeneratedwithprogressivelybiggerradiususingtheinversedistanceweighted(IDW)algorithmandmergedtogether.Remaininggapsarethenmergedusingnearestneighborinterpolation.Default=3--dem-resolution<float>DSM/DTMresolutionincm/pixel.Default:5--dem-decimation<positiveinteger>DecimatethepointsbeforegeneratingtheDEM.1isnodecimation(fullquality).100decimates~99%ofthepoints.Usefulforspeedingupgeneration.Default=1--dem-euclidean-mapComputesaneuclideanrastermapforeachDEM.ThemapreportsthedistancefromeachcelltothenearestNODATAvalue(beforeanyholefillingtakesplace).Thiscanbeusefultoisolatetheareasthathavebeenfilled.Default:False--orthophoto-resolution<float>0.0>Orthophotoresolutionincm/pixel.Default:5--orthophoto-no-tiledSetthisparameterifyouwantastrippedgeoTIFF.Default:False--orthophoto-compression<string>Setthecompressiontouse.Notethatthiscouldbreakgdal_translateifyoudon't know what you are doing.Options:JPEG,LZW,PACKBITS,DEFLATE,LZMA,NONE.Default:DEFLATE--orthophoto-bigtiff{YES,NO,IF_NEEDED,IF_SAFER}ControlwhetherthecreatedorthophotoisaBigTIFForclassicTIFF.BigTIFFisavariantforfileslargerthan4GiBofdata.OptionsareYES,NO,IF_NEEDED,IF_SAFER.SeeGDALspecs:https://www.gdal.org/frmt_gtiff.htmlformoreinfo.Default:IF_SAFER--orthophoto-cutlineGeneratesapolygonaroundthecroppingareathatcutstheorthophotoaroundtheedgesoffeatures.Thispolygoncanbeusefulforstitchingseamlessmosaicswithmultipleoverlappingorthophotos.Default:False--build-overviewsBuildorthophotooverviewsusinggdaladdo.--verbose,-vPrintadditionalmessagestotheconsoleDefault:False--timeGeneratesabenchmarkfilewithruntimeinfoDefault:False--versionDisplaysversionnumberandexits.--split<positiveinteger>Averagenumberofimagespersubmodel.Whensplittingalargedatasetintosmallersubmodels,imagesaregroupedintoclusters.Thisvalueregulatesthenumberofimagesthateachclustershouldhaveonaverage.--split-overlap<positiveinteger>Radiusoftheoverlapbetweensubmodels.Aftergroupingimagesintoclusters,imagesthatarecloserthanthisradiustoaclusterareaddedtothecluster.Thisisdonetoensurethatneighboringsubmodelsoverlap.--sm-cluster<string>URLtoanodeodm-proxyinstancefordistributingasplit-mergeworkflowonmultiplenodesinparallel.Default:None--merge<string>Choosewhattomergeinthemergestepinasplitdataset.Bydefaultallavailableoutputsaremerged.Default:all

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.

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.

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:

--orthophoto-resolution is the resolution of the orthophoto in cm/pixel. Increase this value for a higher resolution result.

--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.

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.

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.

Note: Video reconstruction currently will not work out of the box! There’s code in the project that should allow a developer to add SLAM functionality to ODM, but this feature has not been touched in a while and is currently broken.

It is possible to build a reconstruction using a video file instead of still images. The technique for reconstructing the camera trajectory from a video is called Simultaneous Localization And Mapping (SLAM). OpenDroneMap uses the opensource ORB_SLAM2 library for this task.

We will explain here how to use it. We will need to build the SLAM module, calibrate the camera and finally run the reconstruction from a video.

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 are now ready to run the OpenDroneMap pipeline from a video. For this we need the video and a config file for ORB_SLAM2. Here’s an example config.yaml. Before using it, copy-paste the calibration parameters for your camera that you just computed on the previous section.

Put the video and the config.yaml file on an empty folder. Then run OpenDroneMap using the following command:

where PROJECT_PATH is the path to the folder containing the video and config file, VIDEO.mp4 is the name of your video, and VIDEO_WIDTH is the width of the video (for example, 1920 for an HD video).

That command will run the pipeline starting with SLAM and continuing with stereo matching and mesh reconstruction and texturing.

When done, the textured model will be in PROJECT_PATH/odm_texturing/odm_textured_model.obj. The point cloud created by the stereo matching algorithm will be in PROJECT_PATH/pmvs/recon0/models/option-0000.ply

It is highly recommended that you calibrate your images to reduce lens distortion. Doing so will increase the likelihood of finding quality matches between photos and reduce processing time. You can do this in Photoshop or ImageMagick. We also have some simple scripts to perform this task: https://github.com/OpenDroneMap/CameraCalibration . This suite of scripts will find camera matrix and distortion parameters with a set of checkerboard images, then use those parameters to remove distortion from photos.

The undistort.py script depends on exiftool to copy exif metadata to the new images, so on Windows you may have to use Docker for the undistort step. Put the matrix.txt and distortion.txt in their own directory (eg. sample/config) and do the following::