opendronemap / dem2mesh

Quickly generate 2.5D meshes from elevation models.

An open source command line toolkit for processing aerial drone imagery. ODM turns simple 2D images into:

• Classified Point Clouds
• 3D Textured Models
• Georeferenced Orthorectified Imagery
• Georeferenced Digital Elevation Models

The application is available for Windows, Mac and Linux and it works from the command line, making it ideal for power users, scripts and for integration with other software.

If you would rather not type commands in a shell and are looking for a friendly user interface, check out WebODM.

Quickstart

The easiest way to run ODM on is via docker. To install docker, see docs.docker.com. Once you have docker installed and working, you can run ODM by placing some images (JPEGs or TIFFs) in a folder named “images” (for example C:\Users\youruser\datasets\project\images or /home/youruser/datasets/project/images) and simply run from a Command Prompt / Terminal:

# Windows
docker run -ti --rm -v c:/Users/youruser/datasets:/datasets opendronemap/odm --project-path /datasets project

# Mac/Linux
docker run -ti --rm -v /home/youruser/datasets:/datasets opendronemap/odm --project-path /datasets project

You can pass additional parameters by appending them to the command:

docker run -ti --rm -v /datasets:/datasets opendronemap/odm --project-path /datasets project [--additional --parameters --here]

For example, to generate a DSM (--dsm) and increase the orthophoto resolution (--orthophoto-resolution 2) :

docker run -ti --rm -v /datasets:/datasets opendronemap/odm --project-path /datasets project --dsm --orthophoto-resolution 2

Viewing Results

When the process finishes, the results will be organized as follows:

|-- images/
    |-- img-1234.jpg
    |-- ...
|-- opensfm/
    |-- see mapillary/opensfm repository for more info
|-- odm_meshing/
    |-- odm_mesh.ply                    # A 3D mesh
|-- odm_texturing/
    |-- odm_textured_model.obj          # Textured mesh
    |-- odm_textured_model_geo.obj      # Georeferenced textured mesh
|-- odm_georeferencing/
    |-- odm_georeferenced_model.laz     # LAZ format point cloud
|-- odm_orthophoto/
    |-- odm_orthophoto.tif              # Orthophoto GeoTiff

You can use the following free and open source software to open the files generated in ODM:

• .tif (GeoTIFF): QGIS
• .laz (Compressed LAS): CloudCompare
• .obj (Wavefront OBJ), .ply (Stanford Triangle Format): MeshLab

Note! Opening the .tif files generated by ODM in programs such as Photoshop or GIMP might not work (they are GeoTIFFs, not plain TIFFs). Use QGIS instead.

API

ODM can be made accessible from a network via NodeODM.

Documentation

See http://docs.opendronemap.org for tutorials and more guides.

Forum

We have a vibrant community forum. You can search it for issues you might be having with ODM and you can post questions there. We encourage users of ODM to participate in the forum and to engage with fellow drone mapping users.

Windows Setup

ODM can be installed natively on Windows. Just download the latest setup from the releases page. After opening the ODM Console you can process datasets by typing:

run C:\Users\youruser\datasets\project  [--additional --parameters --here]

GPU Acceleration

ODM has support for doing SIFT feature extraction on a GPU, which is about 2x faster than the CPU on a typical consumer laptop. To use this feature, you need to use the opendronemap/odm:gpu docker image instead of opendronemap/odm and you need to pass the --gpus all flag:

docker run -ti --rm -v c:/Users/youruser/datasets:/datasets --gpus all opendronemap/odm:gpu --project-path /datasets project

When you run ODM, if the GPU is recognized, in the first few lines of output you should see:

[INFO]    Writing exif overrides
[INFO]    Maximum photo dimensions: 4000px
[INFO]    Found GPU device: Intel(R) OpenCL HD Graphics
[INFO]    Using GPU for extracting SIFT features

The SIFT GPU implementation is CUDA-based, so should work with most NVIDIA graphics cards of the GTX 9xx Generation or newer.

If you have an NVIDIA card, you can test that docker is recognizing the GPU by running:

docker run --rm --gpus all nvidia/cuda:10.0-base nvidia-smi

If you see an output that looks like this:

Fri Jul 24 18:51:55 2020       
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 440.82       Driver Version: 440.82       CUDA Version: 10.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |

You're in good shape!

See https://github.com/NVIDIA/nvidia-docker and https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker for information on docker/NVIDIA setup.

Native Install (Ubuntu 21.04)

You can run ODM natively on Ubuntu 21.04 (although we don't recommend it):

git clone https://github.com/OpenDroneMap/ODM
cd ODM
bash configure.sh install

You can then process datasets with ./run.sh /datasets/odm_data_aukerman

Native Install (MacOS)

You can run ODM natively on Intel/ARM MacOS.

First install:

• Xcode 13 (not 14, there's currently a bug)
• Homebrew

Then Run:

git clone https://github.com/OpenDroneMap/ODM
cd ODM
bash configure_macos.sh install

You can then process datasets with ./run.sh /datasets/odm_data_aukerman

This could be improved in the future. Helps us create a Homebrew formula.

Updating a native installation

When updating to a newer version of native ODM, it is recommended that you run:

bash configure.sh reinstall

to ensure all the dependent packages and modules get updated.

Build Docker Images From Source

If you want to rebuild your own docker image (if you have changed the source code, for example), from the ODM folder you can type:

docker build -t my_odm_image --no-cache .

When building your own Docker image, if image size is of importance to you, you should use the --squash flag, like so:

docker build --squash -t my_odm_image .

This will clean up intermediate steps in the Docker build process, resulting in a significantly smaller image (about half the size).

Experimental flags need to be enabled in Docker to use the --squash flag. To enable this, insert the following into the file /etc/docker/daemon.json:

{
   "experimental": true
}

After this, you must restart docker.

Video Support

Starting from version 3.0.4, ODM can automatically extract images from video files (.mp4, .mov, .lrv, .ts). Just place one or more video files into the images folder and run the program as usual. Subtitles files (.srt) with GPS information are also supported. Place .srt files in the images folder, making sure that the filenames match. For example, my_video.mp4 ==> my_video.srt (case-sensitive).

Developers

Help improve our software! We welcome contributions from everyone, whether to add new features, improve speed, fix existing bugs or add support for more cameras. Check our code of conduct, the contributing guidelines and how decisions are made.

Installation and first run

For Linux users, the easiest way to modify the software is to make sure docker is installed, clone the repository and then run from a shell:

$ DATA=/path/to/datasets ./start-dev-env.sh

Where /path/to/datasets is a directory where you can place test datasets (it can also point to an empty directory if you don't have test datasets).

Run configure to set up the required third party libraries:

(odmdev) [user:/code] master+* ± bash configure.sh reinstall

You can now make changes to the ODM source. When you are ready to test the changes you can simply invoke:

(odmdev) [user:/code] master+* ± ./run.sh --project-path /datasets mydataset

Stop dev container

 docker  stop odmdev

To come back to dev environement

change your_username to your username

docker start odmdev
docker exec -ti odmdev bash
su your_username

If you have questions, join the developer's chat at https://community.opendronemap.org/c/developers-chat/21

1. Try to keep commits clean and simple
2. Submit a pull request with detailed changes and test results
3. Have fun!

Troubleshooting

The dev environment makes use of opendronemap/nodeodm by default. You may want to run docker pull opendronemap/nodeodm before running ./start-dev-env.sh to avoid using an old cached version.

In order to make a clean build, remove ~/.odm-dev-home and ODM/.setupdevenv.

Credits

ODM makes use of several libraries and other awesome open source projects to perform its tasks. Among them we'd like to highlight:

• OpenSfM
• OpenMVS
• PDAL
• Entwine
• MVS Texturing
• GRASS GIS
• GDAL
• PoissonRecon

Citation

OpenDroneMap Authors ODM - A command line toolkit to generate maps, point clouds, 3D models and DEMs from drone, balloon or kite images. OpenDroneMap/ODM GitHub Page 2020; https://github.com/OpenDroneMap/ODM

Trademark

See Trademark Guidelines

dem2mesh's Issues

AMD Segmentation fault

On AMD, while processing a particularly large dataset, I'm experiencing a segfault during the edge collapse phase. This doesn't appear to occur on intel.

Eg:

./dem2mesh -inputFile mesh_dsm.tif -outputFile odm_25dmesh.dirty.ply -maxTileLength 2000 -maxVertexCount 200000 -edgeSwapThreshold 0.15 -verbose

... snip ...

iteration 90 - triangles 5391543 threshold 6.95688
iteration 95 - triangles 4981377 threshold 9.03921
Performing edge collapses...
[1]    438838 segmentation fault (core dumped)  ./dem2mesh -inputFile mesh_dsm.tif -outputFile odm_25dmesh.dirty.ply  2000  

I'm experiencing this crash when using opendronemap/nodeodm image as well as building dem2mesh manually.

lscpu
Architecture:            x86_64
  CPU op-mode(s):        32-bit, 64-bit
  Address sizes:         48 bits physical, 48 bits virtual
  Byte Order:            Little Endian
CPU(s):                  32
  On-line CPU(s) list:   0-31
Vendor ID:               AuthenticAMD
  Model name:            AMD Ryzen 9 7950X 16-Core Processor
    CPU family:          25
    Model:               97
    Thread(s) per core:  2
    Core(s) per socket:  16
    Socket(s):           1
    Stepping:            2
    Frequency boost:     enabled
    CPU(s) scaling MHz:  52%
    CPU max MHz:         5879.8818
    CPU min MHz:         3000.0000
    BogoMIPS:            8983.39
    Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ht syscall nx mmxext fxsr_opt pdpe
                         1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid extd_apicid aperfmperf rapl pni pclmulqdq monitor ssse3 fma cx16 sse4_1 s
                         se4_2 x2apic movbe popcnt aes xsave avx f16c rdrand lahf_lm cmp_legacy svm extapic cr8_legacy abm sse4a misalignsse 3dnowprefetch os
                         vw ibs skinit wdt tce topoext perfctr_core perfctr_nb bpext perfctr_llc mwaitx cpb cat_l3 cdp_l3 hw_pstate ssbd mba perfmon_v2 ibrs 
                         ibpb stibp vmmcall fsgsbase bmi1 avx2 smep bmi2 erms invpcid cqm rdt_a avx512f avx512dq rdseed adx smap avx512ifma clflushopt clwb a
                         vx512cd sha_ni avx512bw avx512vl xsaveopt xsavec xgetbv1 xsaves cqm_llc cqm_occup_llc cqm_mbm_total cqm_mbm_local avx512_bf16 clzero
                          irperf xsaveerptr rdpru wbnoinvd cppc arat npt lbrv svm_lock nrip_save tsc_scale vmcb_clean flushbyasid decodeassists pausefilter p
                         fthreshold avic v_vmsave_vmload vgif v_spec_ctrl avx512vbmi umip pku ospke avx512_vbmi2 gfni vaes vpclmulqdq avx512_vnni avx512_bita
                         lg avx512_vpopcntdq rdpid overflow_recov succor smca fsrm flush_l1d
Virtualization features: 
  Virtualization:        AMD-V
Caches (sum of all):     
  L1d:                   512 KiB (16 instances)
  L1i:                   512 KiB (16 instances)
  L2:                    16 MiB (16 instances)
  L3:                    64 MiB (2 instances)
NUMA:                    
  NUMA node(s):          1
  NUMA node0 CPU(s):     0-31

Add Multi-Thread Support

When multiple tiles are being processed, the user should be able to choose to process multiple tiles in parallel.

This will increase memory usage.

I added dockerfile

I added dockerfile