An open source command line toolkit for processing aerial drone imagery
 
 
 
 
 
 
Go to file
Piero Toffanin 8410186b66 Don't let PDAL resolve canonical paths while searching for drivers 2023-01-03 08:07:54 -05:00
.github/workflows Remove broken action 2022-12-05 23:10:29 -05:00
SuperBuild Set python path to build pdal-python 2022-12-13 15:22:12 -05:00
contrib Merge pull request #1551 from pierotofy/300 2022-11-23 14:25:24 -05:00
docker Missing then 2021-09-03 12:49:46 -04:00
docs Update issue_template.md 2022-07-01 10:22:55 -04:00
licenses Fix various typos 2022-01-08 05:38:36 -05:00
opendm feat: added "DJI Mavic Air 1" to rollingshutter.py 2022-12-24 15:23:32 +01:00
snap Set PROJ_LIB 2022-10-15 17:06:53 -04:00
stages Cleanup orthophoto_render.tif 2022-12-28 14:21:29 -05:00
tests Fix typos (#1497) 2022-07-10 15:02:10 -04:00
.dockerignore Updated dockefiles to best practices ready for multi stage builds 2020-02-29 10:54:26 +10:00
.gitignore AI-powered automatic sky removal 2022-07-14 16:02:59 -04:00
.gitmodules Removed vpckg submodule 2021-04-21 09:28:58 -04:00
CNAME Create CNAME 2017-07-31 11:29:25 -04:00
CONTRIBUTING.md Update CONTRIBUTING.md 2020-04-14 11:24:53 -04:00
Dockerfile Don't let PDAL resolve canonical paths while searching for drivers 2023-01-03 08:07:54 -05:00
LICENSE Update LICENSE to AGPLv3 2020-11-24 08:32:05 -05:00
README.md opendronemap available on edge 2022-11-18 15:29:32 -05:00
VERSION Transform shots.geojson, bump opensfm, bump version 2022-12-12 20:09:29 +00:00
code_of_conduct.md Update code_of_conduct.md 2020-04-14 11:26:22 -04:00
configure.py Save some space during Windows build 2022-06-06 13:52:44 -04:00
configure.sh Upgrade rasterio 2022-01-12 12:37:47 -05:00
configure_macos.sh Final touches 2022-09-15 15:13:33 -04:00
console.bat Tweaks, innosetup draft 2021-05-12 16:01:50 -04:00
gpu.Dockerfile Don't let PDAL resolve canonical paths while searching for drivers 2023-01-03 08:07:54 -05:00
innosetup.iss Handle CTRL+C 2021-05-19 15:39:36 -04:00
odm_docker_readme.txt Update odm_docker_readme.txt 2018-03-23 11:43:50 -03:00
portable.Dockerfile Don't let PDAL resolve canonical paths while searching for drivers 2023-01-03 08:07:54 -05:00
requirements.txt Add CODEM deps 2022-12-13 17:41:59 +00:00
run.bat NONINTERACTIVE mode, call run.bat from different drives 2021-05-25 09:43:39 -04:00
run.py rm_r based rerun-all 2022-01-03 09:21:46 -05:00
run.sh Final touches 2022-09-15 15:13:33 -04:00
settings.yaml Update settings.yaml 2020-04-02 18:48:29 -05:00
start-dev-env.sh Update start-dev-env.sh, OpenMVS 2021-10-22 13:03:48 -04:00
test.sh Started migration to 18.04, Python3.6 2020-09-08 13:08:57 -04:00
vcpkg-requirements.txt vcpkg additions, tweaks 2021-05-12 14:24:12 -04:00
win32env.bat Merge pull request #1526 from coumbsek/bugfix/single_quote_in_ODM_path 2022-08-24 09:48:07 +02:00
winrun.bat mod: forcing python to use utf8 2022-03-23 08:20:07 +01:00

README.md

ODM Logo

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

images-diag

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]

Snap Package

ODM is now available as a Snap Package from the Snap Store. To install you may use the Snap Store (available itself as a Snap Package) or the command line:

sudo snap install --edge opendronemap

To run, you will need a terminal window into which you can type:

opendronemap

# or

snap run opendronemap

# or

/snap/bin/opendronemap

Snap packages will be kept up-to-date automatically, so you don't need to update ODM manually.

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.

WSL or WSL2 Install

Note: This requires that you have installed WSL already by following the instructions on Microsoft's Website.

You can run ODM via WSL or WSL2 by downloading the rootfs.tar.gz file from the releases page on GitHub. Once you have the file saved to your Downloads folder in Windows, open a PowerShell or CMD window by right-clicking the Flag Menu (bottom left by default) and selecting "Windows PowerShell", or alternatively by using the Windows Terminal from the Windows Store.

Inside a PowerShell window, or Windows Terminal running PowerShell, type the following:

# PowerShell
wsl.exe --import ODM $env:APPDATA\ODM C:\path\to\your\Downloads\rootfs.tar.gz

Alternatively if you're using CMD.exe or the CMD support in Windows Terminal type:

# CMD
wsl.exe --import ODM %APPDATA%\ODM C:\path\to\your\Downloads\rootfs.tar.gz

In either case, make sure you replace C:\path\to\your\Downloads\rootfs.tar.gz with the actual path to your rootfs.tar.gz file.

This will save a new Hard Disk image to your Windows AppData folder at C:\Users\username\AppData\roaming\ODM (where username is your Username in Windows), and will set-up a new WSL "distro" called ODM.

You may start the ODM distro by using the relevant option in the Windows Terminal (from the Windows Store) or by executing wsl.exe -d ODM in a PowerShell or CMD window.

ODM is installed to the distro's /code directory. You may execute it with:

/code/run.sh

Updating ODM in WSL

The easiest way to update the installation of ODM is to download the new rootfs.tar.gz file and import it as another distro. You may then unregister the original instance the same way you delete ODM from WSL (see next heading).

Deleting an ODM in WSL instance

wsl.exe --unregister ODM

Finally you'll want to delete the files by using your Windows File Manager (Explorer) to navigate to %APPDATA%, find the ODM directory, and delete it by dragging it to the recycle bin. To permanently delete it empty the recycle bin.

If you have installed to a different directory by changing the --import command you ran to install you must use that directory name to delete the correct files. This is likely the case if you have multiple ODM installations or are updating an already-installed installation.

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.

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.

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

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:

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