OpenDroneMap-WebODM/README.md

323 wiersze
16 KiB
Markdown
Czysty Zwykły widok Historia

2016-08-15 19:54:31 +00:00
# WebODM
2017-06-09 19:04:54 +00:00
[![Build Status](https://travis-ci.org/OpenDroneMap/WebODM.svg?branch=master)](https://travis-ci.org/OpenDroneMap/WebODM) [![Join Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/OpenDroneMap/web-development) [![GitHub version](https://badge.fury.io/gh/OpenDroneMap%2FWebODM.svg)](https://badge.fury.io/gh/OpenDroneMap%2FWebODM)
2016-10-05 20:38:50 +00:00
2017-07-26 03:07:54 +00:00
A free, user-friendly, extendable application and [API](http://docs.webodm.org) for drone image processing. Generate georeferenced maps, point clouds, elevation models and textured 3D models from aerial images. It uses [OpenDroneMap](https://github.com/OpenDroneMap/OpenDroneMap) for processing.
2016-08-15 19:54:31 +00:00
2017-04-30 20:14:41 +00:00
* [Getting Started](#getting-started)
* [Common Troubleshooting](#common-troubleshooting)
* [Add More Processing Nodes](#add-more-processing-nodes)
* [Security](#security)
2017-08-09 16:48:18 +00:00
* [Where Are My Files Stored?](#where-are-my-files-stored)
2017-04-30 20:14:41 +00:00
* [API Docs](#api-docs)
* [Run the docker version as a Linux Service](#run-the-docker-version-as-a-linux-service)
* [Run it natively](#run-it-natively)
* [OpenDroneMap, node-OpenDroneMap, WebODM... what?](#opendronemap-node-opendronemap-webodm-what)
* [Roadmap](#roadmap)
* [Terminology](#terminology)
2017-06-05 22:48:04 +00:00
* [Getting Help](#getting-help)
2017-04-30 20:14:41 +00:00
![Alt text](https://user-images.githubusercontent.com/1951843/28586405-af18e8cc-7141-11e7-9853-a7feca7c9c6b.gif)
2016-09-12 00:08:31 +00:00
![Alt text](/screenshots/ui-mockup.png?raw=true "WebODM")
2017-01-21 18:11:46 +00:00
![Alt text](/screenshots/pointcloud.png?raw=true "3D Display")
![Alt text](https://user-images.githubusercontent.com/1951843/28586977-8588ebfe-7143-11e7-94d6-a66bf02c1517.png)
2017-06-06 20:08:08 +00:00
If you know Python, web technologies (JS, HTML, CSS, etc.) or both, it's easy to make a change to WebODM! Make a fork, clone the repository and run `./devenv.sh start`. That's it! See the [Development Quickstart](http://docs.webodm.org/#development-quickstart) and [Contributing](/CONTRIBUTING.md) documents for more information. All ideas are considered and people of all skill levels are welcome to contribute.
2016-09-12 00:08:31 +00:00
## Getting Started
2016-12-01 16:50:33 +00:00
* Install the following applications (if they are not installed already):
2016-12-01 16:35:26 +00:00
- [Docker](https://www.docker.com/)
- [Python](https://www.python.org/downloads/)
- [Git](https://git-scm.com/downloads)
2016-09-12 00:08:31 +00:00
* From the Docker Quickstart Terminal (Windows) or from the command line (Mac / Linux) type:
```bash
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input
2016-09-12 00:08:31 +00:00
cd WebODM
./webodm.sh start
2016-09-12 00:08:31 +00:00
```
* If you're on Windows find the IP of your Docker machine by running this command from your Docker Quickstart Terminal:
2016-09-12 00:08:31 +00:00
```bash
2016-09-12 00:08:31 +00:00
docker-machine ip
```
Linux / Mac, users can connect to 127.0.0.1.
2016-09-12 00:08:31 +00:00
* Open a Web Browser to `http://<yourDockerMachineIp>:8000`
To stop WebODM press CTRL+C or run:
```
./webodm.sh stop
```
To update WebODM to the latest version use:
```bash
./webodm.sh update
```
We recommend that you read the [Docker Documentation](https://docs.docker.com/) to familiarize with the application lifecycle, setup and teardown, or for more advanced uses. Look at the contents of the webodm.sh script to understand what commands are used to launch WebODM.
2016-12-01 16:42:53 +00:00
2017-06-17 13:33:17 +00:00
For Windows users an [Installer](https://www.webodm.org/installer) is also available.
### Common Troubleshooting
2017-03-10 22:33:11 +00:00
Sympthoms | Possible Solutions
--------- | ------------------
While starting WebODM you get: `from six.moves import _thread as thread ImportError: cannot import name _thread` | Try running: `sudo pip install --ignore-installed six`
Task output or console shows one of the following:<ul><li>`MemoryError`</li><li>`Killed`</li></ul> | Make sure that your Docker environment has enough RAM allocated: [MacOS Instructions](http://stackoverflow.com/a/39720010), [Windows Instructions](https://docs.docker.com/docker-for-windows/#advanced)
2017-03-10 22:33:11 +00:00
After an update, you get: `django.contrib.auth.models.DoesNotExist: Permission matching query does not exist.` | Try to remove your WebODM folder and start from a fresh git clone
Task fails with `Process exited with code null`, no task console output | If the computer running node-opendronemap is using an old or 32bit CPU, you need to compile [OpenDroneMap](https://github.com/OpenDroneMap/OpenDroneMap) from sources and setup node-opendronemap natively. You cannot use docker. Docker images work with CPUs with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support or higher.
On Windows, docker-compose fails with `Failed to execute the script docker-compose` | Make sure you have enabled VT-x virtualization in the BIOS
Cannot access WebODM using Microsoft Edge on Windows 10 | Try to tweak your internet properties according to [these instructions](http://www.hanselman.com/blog/FixedMicrosoftEdgeCantSeeOrOpenVirtualBoxhostedLocalWebSites.aspx)
2017-05-22 13:50:27 +00:00
Getting a `No space left on device` error, but hard drive has enough space left | Docker on Windows by default will allocate only 20GB of space to the default docker-machine. You need to increase that amount. See [this link](http://support.divio.com/local-development/docker/managing-disk-space-in-your-docker-vm) and [this link](https://www.howtogeek.com/124622/how-to-enlarge-a-virtual-machines-disk-in-virtualbox-or-vmware/)
Have you had other issues? Please [report them](https://github.com/OpenDroneMap/WebODM/issues/new) so that we can include them in this document.
2016-12-01 16:35:26 +00:00
### Add More Processing Nodes
WebODM can be linked to one or more processing nodes running [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap). The default configuration already includes a "node-odm-1" processing node which runs on the same machine as WebODM, just to help you get started. As you become more familiar with WebODM, you might want to install processing nodes on separate machines.
Adding more processing nodes will allow you to run multiple jobs in parallel.
You **will not be able to distribute a single job across multiple processing nodes**. We are actively working to bring this feature to reality, but we're not there yet.
### Security
2017-07-11 16:45:41 +00:00
If you want to run WebODM in production, make sure to disable the `DEBUG` flag from `webodm/settings.py` and go through the [Django Deployment Checklist](https://docs.djangoproject.com/en/1.10/howto/deployment/checklist/).
2017-08-09 16:48:18 +00:00
### Where Are My Files Stored?
When using Docker, all processing results are stored in a docker volume and are not available on the host filesystem. If you want to store your files on the host filesystem instead of a docker volume, you need to change a line in `docker-compose.yml` as follows:
From:
```
volumes:
- appmedia:/webodm/app/media
```
To:
```
volumes:
- /path/where/to/store/files:/webodm/app/media
```
Then restart WebODM.
Note that existing task results will not be available after the change. Refer to the [Migrate Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) section of the Docker documentation for information on migrating existing task results.
2017-03-01 23:45:36 +00:00
## API Docs
2017-06-06 20:08:08 +00:00
See the [API documentation page](http://docs.webodm.org).
2017-03-01 23:45:36 +00:00
## Run the docker version as a Linux Service
If you wish to run the docker version with auto start/monitoring/stop, etc, as a systemd style Linux Service, a systemd unit file is included in the service folder of the repo.
2017-04-18 14:47:10 +00:00
2017-04-18 14:45:57 +00:00
This should work on any Linux OS capable of running WebODM, and using a SystemD based service daemon (such as Ubuntu 16.04 server for example).
2017-04-18 14:47:10 +00:00
2017-04-18 14:45:57 +00:00
This has only been tested on Ubuntu 16.04 server.
The following pre-requisites are required:
* Requires odm user
2017-04-18 14:45:57 +00:00
* Requires docker installed via system (ubuntu: `sudo apt-get install docker.io`)
* Requires screen to be installed
* Requires odm user member of docker group
* Required WebODM directory checked out to /opt/WebODM
* Requires that /opt/WebODM is recursively owned by odm:odm
If all pre-requisites have been met, and repository is checked out to /opt/WebODM folder, then you can use the following steps to enable and manage the service:
First, to install the service, and enable the service to run at startup from now on:
```bash
2017-04-18 14:45:57 +00:00
sudo systemctl enable /opt/WebODM/service/webodm.service
```
To manually stop the service:
```bash
2017-04-18 14:45:57 +00:00
sudo systemctl stop webodm
```
To manually start the service:
```bash
2017-04-18 14:45:57 +00:00
sudo systemctl start webodm
```
To manually check service status:
```bash
2017-04-18 14:45:57 +00:00
sudo systemctl status webodm
```
The service runs within a screen session, so as the odm user you can easily jump into the screen session by using:
```bash
2017-04-18 14:47:10 +00:00
screen -r webodm
```
(if you wish to exit the screen session, don't use ctrl+c, that will kill webodm, use `CTRL+A` then hit the `D` key)
2016-09-12 00:08:31 +00:00
## Run it natively
WebODM can run natively on Windows, MacOS and Linux.
2017-05-21 19:13:04 +00:00
Ubuntu 16.04 LTS users can refer to [this script](/contrib/ubuntu_1604_install.sh) to install WebODM natively on a new machine.
To run WebODM, you will need to install:
2016-09-12 00:08:31 +00:00
* PostgreSQL (>= 9.5)
* PostGIS 2.3
* Python 3.5
2016-12-13 15:11:14 +00:00
* GDAL (>= 2.1)
* Node.js (>= 6.0)
* Nginx (Linux/MacOS) - OR - Apache + mod_wsgi (Windows)
2016-09-12 00:08:31 +00:00
On Linux, make sure you have:
```bash
apt-get install binutils libproj-dev gdal-bin nginx
```
2016-12-01 16:35:26 +00:00
On Windows use the [OSGeo4W](https://trac.osgeo.org/osgeo4w/) installer to install GDAL. MacOS users can use:
```
brew install postgres postgis
```
2016-09-12 00:08:31 +00:00
Then these steps should be sufficient to get you up and running:
```bash
2016-09-12 00:08:31 +00:00
git clone https://github.com/OpenDroneMap/WebODM
```
Create a `WebODM/webodm/local_settings.py` file containing your database settings:
2016-09-12 00:08:31 +00:00
```python
2016-09-12 00:08:31 +00:00
DATABASES = {
'default': {
'ENGINE': 'django.contrib.gis.db.backends.postgis',
2016-09-12 00:08:31 +00:00
'NAME': 'webodm_dev',
'USER': 'postgres',
'PASSWORD': 'postgres',
'HOST': 'localhost',
'PORT': '5432',
}
}
```
From psql or [pgadmin](https://www.pgadmin.org), connect to PostgreSQL, create a new database (name it `webodm_dev`), connect to it and set the [postgis.enable_outdb_rasters](http://postgis.net/docs/manual-2.2/postgis_enable_outdb_rasters.html) and [postgis.gdal_enabled_drivers](http://postgis.net/docs/postgis_gdal_enabled_drivers.html) settings:
```sql
ALTER SYSTEM SET postgis.enable_outdb_rasters TO True;
ALTER SYSTEM SET postgis.gdal_enabled_drivers TO 'GTiff';
```
2016-09-12 00:08:31 +00:00
Then:
```bash
2016-09-12 00:08:31 +00:00
pip install -r requirements.txt
sudo npm install -g webpack
npm install
webpack
python manage.py collectstatic --noinput
chmod +x start.sh && ./start.sh --no-gunicorn
```
The `start.sh` script will use Django's built-in server if you pass the `--no-gunicorn` parameter. This is good for testing, but bad for production.
In production, if you have nginx installed, modify the configuration file in `nginx/nginx.conf` to match your system's configuration and just run `start.sh` without parameters.
Windows users should refer to [this guide](https://docs.djangoproject.com/en/1.11/howto/deployment/wsgi/modwsgi/) to install Apache + mod_wsgi and run gunicorn:
```bash
gunicorn webodm.wsgi --bind 0.0.0.0:8000 --preload
2016-09-12 00:08:31 +00:00
```
If you are getting a `rt_raster_gdal_warp: Could not create GDAL transformation object for output dataset creation`, make sure that your PostGIS installation has PROJ support:
```sql
SELECT PostGIS_Full_Version();
```
You may also need to set the environment variable PROJSO to the .so or .dll projection library your PostGIS is using. This just needs to have the name of the file. So for example on Windows, you would in Control Panel -> System -> Environment Variables add a system variable called PROJSO and set it to libproj.dll (if you are using proj 4.6.1). You'll have to restart your PostgreSQL service/daemon after this change. [http://postgis.net/docs/manual-2.0/RT_ST_Transform.html](http://postgis.net/docs/manual-2.0/RT_ST_Transform.html)
2017-01-19 22:34:01 +00:00
If you are using Windows and are unable to go past the `pip install -r requirements.txt` command because of an error regarding zlib and Pillow, manually edit the `requirements.txt` file, remove the Pillow requirement and run:
```bash
easy_install pillow
pip install -r requirements.txt
```
On Windows make sure that all of your PATH environment variables are set properly. These commands:
```bash
python --version
pip --version
npm --version
gdalinfo --version
```
Should all work without errors.
2017-04-30 20:02:16 +00:00
## OpenDroneMap, node-OpenDroneMap, WebODM... what?
The [OpenDroneMap project](https://github.com/OpenDroneMap/) is composed of several components.
- [OpenDroneMap](https://github.com/OpenDroneMap/OpenDroneMap) is a command line toolkit that processes aerial images. Users comfortable with the command line are probably OK using this component alone.
- [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap) is a lightweight interface and API (Application Program Interface) built directly on top of [OpenDroneMap](https://github.com/OpenDroneMap/OpenDroneMap). Users not comfortable with the command line can use this interface to process aerial images and developers can use the API to build applications. Features such as user authentication, map displays, etc. are not provided.
- [WebODM](https://github.com/OpenDroneMap/WebODM) adds more features such as user authentication, map displays, 3D displays, a higher level API and the ability to orchestrate multiple processing nodes (run jobs in parallel). Processing nodes are simply servers running [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap).
2017-04-30 20:02:16 +00:00
![webodm](https://cloud.githubusercontent.com/assets/1951843/25567386/5aeec7aa-2dba-11e7-9169-aca97b70db79.png)
In general, follow these guidelines to find out what you should use:
I am a... | Best choice
--------- | -----------
End user, I'm not really comfortable with the command line | [WebODM](https://github.com/OpenDroneMap/WebODM)
End user, I like shell commands, I need to process images for myself. I use other software to display processing results | [OpenDroneMap](https://github.com/OpenDroneMap/OpenDroneMap)
End user, I can work with the command line, but I'd rather not. I use other software to display processing results | [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap)
End user, I need a drone mapping application for my organization that everyone can use. | [WebODM](https://github.com/OpenDroneMap/WebODM)
2017-04-30 20:02:16 +00:00
Developer, I'm looking to build an app that displays map results and takes care of things like permissions | [WebODM](https://github.com/OpenDroneMap/WebODM)
Developer, I'm looking to build an app that will stay behind a firewall and just needs raw results | [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap)
2016-08-15 19:54:31 +00:00
## Roadmap
- [X] User Registration / Authentication
2016-09-12 00:08:31 +00:00
- [X] UI mockup
- [X] Task Processing
2016-11-11 17:55:56 +00:00
- [X] 2D Map Display
2017-01-21 18:11:46 +00:00
- [X] 3D Model Display
2017-07-13 21:38:51 +00:00
- [ ] NDVI display
- [ ] Volumetric Measurements
2016-10-26 21:29:27 +00:00
- [X] Cluster management and setup.
2016-08-15 19:54:31 +00:00
- [ ] Mission Planner
- [ ] Plugins/Webhooks System
2016-10-26 21:29:27 +00:00
- [X] API
2017-03-01 23:45:36 +00:00
- [X] Documentation
- [ ] Android Mobile App
- [ ] iOS Mobile App
- [ ] Processing Nodes Volunteer Network
2016-10-26 21:29:27 +00:00
- [X] Unit Testing
2017-01-10 03:13:08 +00:00
Don't see a feature that you want? [Help us make it happen](/CONTRIBUTING.md).
2016-08-15 19:54:31 +00:00
2016-08-16 22:03:40 +00:00
## Terminology
- `Project`: A collection of tasks (successfully processed, failed, waiting to be executed, etc.)
- `Task`: A collection of input aerial images and an optional set of output results derived from the images, including an orthophoto, a georeferenced model and a textured model. A `Task`'s output is processed by OpenDroneMap.
2016-08-16 22:08:53 +00:00
- `ProcessingNode`: An instance usually running on a separate VM, or on a separate machine which accepts aerial images, runs OpenDroneMap and returns the processed results (orthophoto, georeferenced model, etc.). Each node communicates with WebODM via a lightweight API such as [node-OpenDroneMap](https://www.github.com/pierotofy/node-OpenDroneMap). WebODM manages the distribution of `Task` to different `ProcessingNode` instances.
2016-08-16 22:03:40 +00:00
- `ImageUpload`: aerial images.
- `Mission`: A flight path and other information (overlap %, angle, ...) associated with a particular `Task`.
2017-06-05 22:48:04 +00:00
## Getting Help
We have several channels of communication for people to ask questions and to get involved with the community:
2017-10-19 21:28:51 +00:00
- [OpenDroneMap Community Forum](http://community.opendronemap.org/c/webodm)
- [Report Issues](https://github.com/OpenDroneMap/WebODM/issues)
We also have a [Gitter Chat](https://gitter.im/OpenDroneMap/web-development), but the preferred way to communicate is via the [OpenDroneMap Community Forum](http://community.opendronemap.org/c/webodm).