mirror
/
OpenDroneMap-ODM
kopia lustrzana https://github.com/OpenDroneMap/ODM
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Update to current version, general cleanup

master
Dakota Benjamin 2016-08-09 16:40:18 -04:00
rodzic 4f51e55759
commit a406d003f4
15 zmienionych plików z 250 dodań i 211 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

51
1.-Installation.md

@ -1,51 +0,0 @@
## How to install OpenDroneMap
Prerequisites:
- Requires Ubuntu 14.04.
- Highly recommended to have at least 4GB of RAM
Install Git tools
```sudo apt-get install git-core```
Git Clone the repository
```
git clone https://github.com/OpenDroneMap/OpenDroneMap.git
cd OpenDroneMap
bash configure.sh
mkdir build && cd build && cmake .. && make && cd ..
```
Check that the install script ends with script finished or something went wrong
Set environment variables:
Using your favorite editor, open `~/.bashrc` and append the following to the bottom of the file (replace [ODM-PATH] with your installation path, e.g. /home/user/OpenDroneMap):
```
export PYTHONPATH=$PYTHONPATH:[ODM-PATH]/SuperBuild/install/lib/python2.7/dist-packages:[ODM-PATH]/SuperBuild/src/opensfm
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:[ODM-PATH]/SuperBuild/install/lib
```
### Common Problems with install:
###### If you get the error `ImportError: No module named ecto`
- Make sure your environment variables are set correctly.
- You can replace `python run.py` with `./run.sh` followed by your normal parameters and that will set the environment variables for that run.
If you get `[ERROR] You must put your pictures into an <images> directory`, your project path must look like this:
```
/home/user/odm_data/
|-- images
|-- IMG_0001.jpg
|-- IMG_0002.jpg
...
|-- gcp_list.txt
...
```
If you get `ImportError: No module named csfm`, your install of OpenSfM may have failed:
```
cd /pat/to/OpenDroneMap/SuperBuild/src/opensfm
python setup.py build
```

121
3.-Run-Time-Parameters.textile

@ -1,121 +0,0 @@
There are the following run time parameters that can be used to adjust the results.
```
-h, --help show this help message and exit
--resize-to <integer>
Resizes images by the largest side. Default: 2400
--job-dir-name <string>
Name of the output folder, only ASCII charaters can be
used. If not provided "reconstruction-with-image-size
-[resize-to]" will be used
--start-with <task>, -s <task>
Start with the provided task. Can be one of: resize |
opensfm | getKeypoints | match | bundler | cmvs | pmvs
| odm_meshing | odm_texturing | odm_georeferencing |
odm_orthophoto
--end-with <task>, -e <task>
Finish at the provided task. Can be one of: resize |
opensfm | getKeypoints | match | bundler | cmvs | pmvs
| odm_meshing | odm_texturing | odm_georeferencing |
odm_orthophoto
--run-only <task> Run only one task. Can be one of: resize | opensfm |
getKeypoints | match | bundler | cmvs | pmvs |
odm_meshing | odm_texturing | odm_georeferencing |
odm_orthophoto
--use-opensfm use OpenSfM to find the camera positions (replaces
getKeypoints, match and bundler steps)
--use-bundler use Bundler to find the camera positions.
--force-focal <positive float>
Override the focal length information for the images
--force-ccd <positive float>
Override the ccd width information for the images
--min-num-features <integer>
Minimum number of features to extract per image. More
features leads to better results but slower execution.
Default: 6000
--matcher-threshold <percent>
Ignore matched keypoints if the two images share less
than <float> percent of keypoints. Default: 2.0
--matcher-ratio <float>
Ratio of the distance to the next best matched
keypoint. Default: 0.6
--matcher-neighbors <integer>
Number of nearest images to pre-match based on GPS
exif data. Set to 0 to skip pre-matching. Neighbors
works together with Distance parameter, set both to 0
to not use pre-matching. OpenSFM uses both parameters
at the same time, Bundler uses only one which has
value, prefering the Neighbors parameter. Default: 8
--matcher-distance <integer>
Distance threshold in meters to find pre-matching
images based on GPS exif data. Set to 0 to skip pre-
matching. Default: 0
--cmvs-maxImages <integer>
The maximum number of images per cluster. Default: 500
--pmvs-level <positive integer>
The level in the image pyramid that is used for the
computation. see
http://www.di.ens.fr/pmvs/documentation.html for more
pmvs documentation. Default: 1
--pmvs-csize < positive integer>
Cell size controls the density of reconstructions.
Default: 2
--pmvs-threshold <float: -1.0 <= x <= 1.0>
A patch reconstruction is accepted as a success and
kept, if its associcated photometric consistency
measure is above this threshold. Default: 0.7
--pmvs-wsize <positive integer>
pmvs samples wsize x wsize pixel colors from each
image to compute photometric consistency score. For
example, when wsize=7, 7x7=49 pixel colors are sampled
in each image. Increasing the value leads to more
stable reconstructions, but the program becomes
slower. Default: 7
--pmvs-minImageNum <positive integer>
Each 3D point must be visible in at least minImageNum
images for being reconstructed. 3 is suggested in
general.
--odm_meshing-maxVertexCount <positive integer>
The maximum vertex count of the output mesh. Default:
100000
--odm_meshing-octreeDepth <positive integer>
Oct-tree depth used in the mesh reconstruction,
increase to get more vertices, recommended values are
8-12, the default is 9
--odm_meshing-samplesPerNode <float >= 1.0>
Number of points per octree node, recommended and
default value: 1.0
--odm_meshing-solverDivide <positive integer>
Oct-tree depth at which the Laplacian equation is
solved in the surface reconstruction step. Increasing
this value increases computation times slightly but
helps reduce memory usage. Default: 9
--odm_texturing-textureResolution <positive integer>
The resolution of the output textures. Must be greater
than textureWithSize. Default: 4096
--odm_texturing-textureWithSize <positive integer>
The resolution to rescale the images performing the
texturing. Default: 3600
--odm_georeferencing-gcpFile <path string>
path to the file containing the ground control points
used for georeferencing. The default file is
gcp_list.txt. The file needs to be on the following
line format: easting northing height pixelrow pixelcol
imagename
--odm_georeferencing-useGcp
Enabling GCPs from the file above. The GCP file is not
used by default.
--odm_orthophoto-resolution <float > 0.0>
Orthophoto ground resolution in pixels/meter. Default:
20.0
--zip-results Compress the results using gunzip
```
Use the parameters in the following way
@./run.py --odm_meshing-maxVertexCount 110000 --odm_meshing-octreeDepth 11@ ...etc
More documentation on cmvs and pmvs available here:
http://www.di.ens.fr/cmvs/documentation.html
http://www.di.ens.fr/pmvs/documentation.html

37
4.-Output-and-Results.md

@ -1,37 +0,0 @@
The output from OpenDroneMap produces 2 subfolders in the folder where your images are located. The folder name is `reconstruction-with-image-size-[resize-to]` by default, but you can specify other name with using the `--job-dir-name` argument.
The two folders are:
**`[job-dir-name]`** (eg.:`reconstruction-with-image-size-2400`) -- contains runtime and temporary files (resized images, logs, temp files, etc...)
**`[job-dir-name]-results`** (eg.:`reconstruction-with-image-size-2400-results`) -- contains all the final product ( point cloud, fully textured meshes, orthophoto, etc..)
## Meshing
`option-0000.ply` -- The point cloud file
`odm_mesh-0000.ply` -- The meshed surface
## Texturing
`odm_texturing/odm_textured_model.obj` -- The textured surface mesh
You can access the point cloud and textured meshes using MeshLab. Open MeshLab, and choose File:Import Mesh and choose your textured mesh from a location similar to the following: `reconstruction-with-image-size-1200-results\odm_texturing\odm_textured_model.obj`
## Georeferencing
`odm_texturing/odm_textured_model_geo.obj` -- The georeferenced and textured surface mesh
`option-0000_georef.ply` -- The georeferenced point cloud
`odm_textured_model_geo_georef_system.txt` -- This file contains the georeference system and coordinate shifting. The X and Y coordinates in the georeferenced mesh if shifted to have smaller values, resulting in smaller mesh files. If you need to work with the real coordinates, this file is useful.
`pointcloud_georef.laz` -- LAZ file
## Orthophoto
`odm_orthphoto.png` -- The orthophoto, but this is a simple png, which don't have any georeferencing information
`odm_orthphoto.tif` -- GeoTIFF Orthophoto. You can use it in QGIS as a raster layer.

28
Docker.md 100644

@ -0,0 +1,28 @@
# Docker
## Installation
(Instructions below apply to Ubuntu 14.04, but the Docker image workflow
has equivalent procedures for Mac OS X and Windows. See [docs.docker.com](docs.docker.com))
OpenDroneMap is Dockerized, meaning you can use containerization to build and run it without tampering with the configuration of libraries and packages already installed on your machine. Docker software is free to install and use in this context. If you don't have it installed, see the [Docker Ubuntu installation tutorial](https://docs.docker.com/engine/installation/linux/ubuntulinux/) and follow the instructions up until "Create a Docker group" inclusive. Once Docker is installed, an OpenDroneMap Docker image can be created like so:
git clone https://github.com/OpenDroneMap/OpenDroneMap.git
cd OpenDroneMap
docker build -t packages -f packages.Dockerfile .
docker build -t odm_image .
docker run -it --user root\
-v $(pwd)/images:/code/images\
-v $(pwd)/odm_orthophoto:/code/odm_orthophoto\
-v $(pwd)/odm_texturing:/code/odm_texturing\
--rm odm_image
## Running
Using this method, the containerized ODM will process the images in the OpenDroneMap/images directory and output results to the OpenDroneMao/odm_orthophoto and OpenDroneMap/odm_texturing directories as described in the [Viewing Results](Output-and-Results.md) section. If you want to view other results outside the Docker image simply add which directories you're interested in to the run command in the same pattern established above. For example, if you're interested in the dense cloud results generated by PMVS and in the orthophoto, simply use the following `docker run` command after building the image:
docker run -it --user root\
-v $(pwd)/images:/code/images\
-v $(pwd)/pmvs:/code/pmvs\
-v $(pwd)/odm_orthophoto:/code/odm_orthophoto\
--rm odm_image
To pass in custom parameters to the run.py script, simply pass it as arguments to the `docker run` command.

36
FAQ.md 100644

@ -0,0 +1,36 @@
# Common Errors
1. `ImportError: No module named ecto`
- Make sure your environment variables are set correctly. You can replace `python run.py` with `./run.sh` followed by your normal parameters and that will set the environment variables for that run.
2. `[ERROR] You must put your pictures into an <images> directory`
- Your project path must look like this:
```
/home/user/odm_data/
|-- images
|-- IMG_0001.jpg
|-- IMG_0002.jpg
...
|-- gcp_list.txt
...
```
3. `ImportError: No module named csfm`
- Your install of OpenSfM may have failed. You can reinstall it manually:
```
cd /path/to/OpenDroneMap/SuperBuild/src/opensfm
python setup.py build
```
4. `[ERROR] quitting cause: /code/SuperBuild/install/bin/pmvs2 /code/pmvs/recon0/ option-0000 returned with code 35072.`
- The most likely reason for this error is that you ran out of memory. You can upgrade your RAM or adjust your CMVS/PMVS settings for better memory management:
- `--resize-to` will reduce the size of the images and the overall memory cost
- Reduce `--cmvs-maxImages` to the smallest number possible without causing CMVS to run on an infinite loop. This will take trial and error, though.
5. OpenSfM is taking a really long time
- If you are using a hyperthreaded processor, you will have to reduce the number of cores OpenSfM uses to the number of physical cores you have (or fewer). This is trivial on a vagrant machine: in your Vagrantfile, reduce the cores allocation to 1 or 2 minus the number of physical cores you have. Otherwise, you will

12
Home.md

@ -1,5 +1,13 @@
Welcome to the OpenDroneMap wiki!
OpenDroneMap is a tool to postprocess small Unmanned Aerial Vehicle (sUAS), balloon, kite, and street view data to geographic data. With the current update, we are adding the ability to create orthophotos from drone, balloon, and kite imagery which has GPS ephemeris. Forked from qwesda/BundlerTools ( https://github.com/qwesda/BundlerTools )
OpenDroneMap is a tool to postprocess small Unmanned Aerial Vehicle (sUAS), balloon, kite, and street view data to geographic data. With the current update, we are adding the ability to create orthophotos from drone, balloon, and kite imagery which has GPS ephemeris.
This is the initial first page and will be developed to explain what OpenDroneMap does, how it does it and how to use it.
### Table of Contents:
- [Installation](Installation.md)
- [Installation using Docker](Docker.md)
- [Running ODM](Running-OpenDroneMap.md)
- [Running using Docker](Docker.md)
- [Run-time Parameters](Run-Time-Parameters.textile)
- [Viewing Results](Output-and-Results.md)
- [FAQ](FAQ.md)

28
Installation.md 100644

@ -0,0 +1,28 @@
## How to install OpenDroneMap
Prerequisites:
- Requires Ubuntu 14.04+ OR a working Docker installation. See [Docker Installation](Docker.md) for instructions installing using Docker.
- Minimum 4GB of RAM
Install Git tools
```sudo apt-get install git-core```
Git Clone the repository
```
git clone https://github.com/OpenDroneMap/OpenDroneMap.git
cd OpenDroneMap
bash configure.sh
mkdir build && cd build && cmake .. && make && cd ..
```
Check that the install script ends with script finished or something went wrong
Set environment variables:
Using your favorite editor, open `~/.bashrc` and append the following to the bottom of the file (replace /your/path/OpenDroneMap with your installation path, e.g. /home/user/OpenDroneMap):
```
export PYTHONPATH=$PYTHONPATH:/your/path/OpenDroneMap/SuperBuild/install/lib/python2.7/dist-packages
export PYTHONPATH=$PYTHONPATH:/your/path/OpenDroneMap/SuperBuild/src/opensfm
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your/path/OpenDroneMap/SuperBuild/install/lib
```

55
Output-and-Results.md 100644

@ -0,0 +1,55 @@
The output from OpenDroneMap produces subfolders in the project folder.
|-- images/
|-- img-1234.jpg
|-- ...
|-- images_resize/
|-- img-1234.jpg
|-- ...
|-- opensfm/ # Tie Points and camera positions here in JSON format
|-- pmvs/
|-- recon0/
|-- models/
|-- option-0000.ply # Dense point cloud
|-- odm_meshing/
|-- odm_mesh.ply # A 3D mesh
|-- odm_meshing_log.txt # Output of the meshing task. May point out errors.
|-- odm_texturing/
|-- odm_textured_model.obj # Textured mesh
|-- odm_textured_model_geo.obj # Georeferenced textured mesh
|-- texture_N.jpg # Associated textured images used by the model
|-- odm_georeferencing/
|-- odm_georeferenced_model.ply # A georeferenced dense point cloud
|-- odm_georeferenced_model.ply.laz # LAZ format point cloud
|-- odm_georeferenced_model.csv # XYZ format point cloud
|-- odm_georeferencing_log.txt # Georeferencing log
|-- odm_georeferencing_utm_log.txt # Log for the extract_utm portion
|-- odm_georeferencing/
|-- odm_orthophoto.png # Orthophoto image (no coordinates)
|-- odm_orthophoto.tif # Orthophoto GeoTiff
|-- odm_orthophoto_log.txt # Log file
|-- gdal_translate_log.txt # Log for georeferencing the png file
## 3D Models
`pmvs/recon0/models/option-0000.ply` -- The point cloud file
`odm_meshing/odm_mesh.ply` -- The meshed surface
## Texturing
`odm_texturing/odm_textured_model.obj` -- The textured surface mesh
You can access the point cloud and textured meshes using MeshLab. Open MeshLab, and choose File:Import Mesh and choose your textured mesh from a location similar to the following: `odm_texturing\odm_textured_model.obj`
## Georeferencing
`odm_texturing/odm_textured_model_geo.obj` -- The georeferenced and textured surface mesh
`odm_georeferenced_model.ply/laz/csv` -- The georeferenced point cloud in different file formats
## Orthophoto
`odm_orthphoto.png` -- The orthophoto, but this is a simple png, which don't have any georeferencing information
`odm_orthphoto.tif` -- GeoTIFF Orthophoto. You can use it in QGIS as a raster layer.

93
Run-Time-Parameters.textile 100644

@ -0,0 +1,93 @@
There are the following run time parameters that can be used to adjust the results.
```
-h, --help show this help message and exit
--project-path <string>
Path to the project to process
--resize-to <integer>
resizes images by the largest side
--start-with <string>, -s <string>
Can be one of: resize | opensfm | cmvs | pmvs | odm_meshing | odm_texturing | odm_georeferencing | odm_orthophoto
--end-with <string>, -e <string>
Can be one of:resize | opensfm | cmvs | pmvs | odm_meshing | odm_texturing | odm_georeferencing | odm_orthophoto
--rerun <string>, -r <string>
Can be one of:resize | opensfm | cmvs | pmvs | odm_meshing | odm_texturing | odm_georeferencing | odm_orthophoto
--rerun-all force rerun of all tasks
--rerun-from <string>
Can be one of:resize | opensfm | cmvs | pmvs | odm_meshing | odm_texturing | odm_georeferencing | odm_orthophoto
--force-focal <positive float>
Override the focal length information for the images
--force-ccd <positive float>
Override the ccd width information for the images
--min-num-features <integer>
Minimum number of features to extract per image. More features leads to better results but slower execution.
Default: 4000
--matcher-threshold <percent>
Ignore matched keypoints if the two images share less than <float> percent of keypoints.
Default: 2.0
--matcher-ratio <float>
Ratio of the distance to the next best matched
keypoint. Default: 0.6
--matcher-neighbors <integer>
Number of nearest images to pre-match based on GPS exif data. Set to 0 to skip pre-matching. Neighbors works together with Distance parameter, set both to 0 to not use pre-matching. OpenSFM uses both parameters at the same time, Bundler uses only one which has value, prefering the Neighbors parameter.
Default: 8
--matcher-distance <integer>
Distance threshold in meters to find pre-matching images based on GPS exif data. Set to 0 to skip pre-matching.
Default: 0
--cmvs-maxImages <integer>
The maximum number of images per cluster. Default: 500
--pmvs-level <positive integer>
The level in the image pyramid that is used for the computation. see http://www.di.ens.fr/pmvs/documentation.html for more pmvs documentation.
Default: 1
--pmvs-csize < positive integer>
Cell size controls the density of reconstructions
Default: 2
--pmvs-threshold <float: -1.0 <= x <= 1.0>
A patch reconstruction is accepted as a success and kept if its associated photometric consistency measure is above this threshold.
Default: 0.7
--pmvs-wsize <positive integer>
pmvs samples wsize x wsize pixel colors from each image to compute photometric consistency score. For example, when wsize=7, 7x7=49 pixel colors are sampled in each image. Increasing the value leads to more stable reconstructions, but the program becomes slower.
Default: 7
--pmvs-minImageNum <positive integer>
Each 3D point must be visible in at least minImageNum images for being reconstructed. 3 is suggested in general.
Default: 3
--pmvs-num-cores <positive integer>
The maximum number of cores to use in dense reconstruction.
Default: 16
--odm_meshing-maxVertexCount <positive integer>
The maximum vertex count of the output mesh
Default: 100000
--odm_meshing-octreeDepth <positive integer>
Oct-tree depth used in the mesh reconstruction, increase to get more vertices, recommended values are 8-12.
Default: 9
--odm_meshing-samplesPerNode <float >= 1.0>
Number of points per octree node, recommended value: 1.0
Default: 1.0
--odm_meshing-solverDivide <positive integer>
Oct-tree depth at which the Laplacian equation is solved in the surface reconstruction step. Increasing this value increases computation times slightly but helps reduce memory usage.
Default: 9
--odm_texturing-textureResolution <positive integer>
The resolution of the output textures. Must be greater than textureWithSize.
Default: 4096
--odm_texturing-textureWithSize <positive integer>
The resolution to rescale the images performing the texturing.
Default: 3600
--odm_georeferencing-gcpFile <path string>
path to the file containing the ground control points used for georeferencing. Default: gcp_list.txt. The file needs to be on the following line format:
easting northing height pixelrow pixelcol imagename
--odm_georeferencing-useGcp
Enabling GCPs from the file above. The GCP file is not used by default.
--odm_orthophoto-resolution <float > 0.0>
Orthophoto ground resolution in pixels/meter
Default: 20.0
--zip-results compress the results using gunzip
--time Generates a benchmark file with runtime info
Default: False
```
Use the parameters in the following way
@./run.py --odm_meshing-maxVertexCount 110000 --odm_meshing-octreeDepth 11@ ...etc
More documentation on cmvs and pmvs available here:
http://www.di.ens.fr/cmvs/documentation.html
http://www.di.ens.fr/pmvs/documentation.html

0
2.-Running-OpenDroneMap.md → Running-OpenDroneMap.md

0
Code-Sprint-Project-Assignment.md → archive/Code-Sprint-Project-Assignment.md

0
Roadmap.md → archive/Roadmap.md

0
Z.1-----Run.Pl---1st-Order-Commands-from-Existing-Perl-Driver-Script.md → archive/Z.1-----Run.Pl---1st-Order-Commands-from-Existing-Perl-Driver-Script.md

0
Z.2----Core-objOpenDroneMap-Specification.md → archive/Z.2----Core-objOpenDroneMap-Specification.md

0
edgarriba-cmake-branch-info-(for-developers).md → archive/edgarriba-cmake-branch-info-(for-developers).md