search

kitbenjamin / googleEarthImageCollection

Collect images from Google Earth that will be used to generate 3-D models.
1 stars 0 forks source link

readme

googleEarthImageCollection

Overview

Definitions

Dependencies

This repo is not designed as a packaged "out of the box" working program. It is a collction of research scripts and little development time is spend making sure if works on the nth computer. The user will have to spend some time making sure all of the dependencies are met - sorry!

OS:

note other versions may also work (testing required)

Install python packages

Install pip with e.g.:

C:/Python27/python.exe get-pip.py

with get-pip.py found in this repository.

Make sure you have PROJ, get it via osgeo: http://download.osgeo.org/osgeo4w/osgeo4w-setup-x86_64.exe Then install packages:

C:/Python27/Scripts/pip.exe install numpy==1.16.5 pandas==0.24.2 pyyaml==5.1.2 pykml==0.1.3 lxml==4.4.1 pyproj==1.9.6 rasterio

Install R packages

Install specific package versions like this:

devtools::install_version("RJSONIO", version = '1.3-1.2')

Usage

Make sure you can run powershell. In admin powershell type:

set-executionpolicy unrestricted

yes to all (A)

Install a region

Run install.bat to create a new directory structure to store images for a given region. These appear as a subdirectory in the regions folder.

Directory Description
googleEarthOut Google Earth images are saved here. Images are moved into subdirectories based the number of times google earth has been re-run e.g. if Google Earth crashes or is restarted by the user
imageInterval Contains csv files with image meta data (camera location, rotation, view domain)
kmlFiles Contains Google Earth 'tour' kml files as well as a folder containing view domain KMLs for every image, making it easy to see what the program has calculated the view domain to be. This includes both the height adjusted and non height adjusted view domains
LOG powershell log files
metaData Contains imageCollectionConfig.yml. This file contains all program parameters.

Edit imageCollectionConfig.yml

Define the directories to Python, R and Google Earth in the imageCollectionConfig.yml.

Define the Google Earth "tour" parameters: e.g. number of images, extent of the sample region.

Parameter Description Units
projection The coordinate system that you are using to define your collection area. This should be in the form of a proj4 string, such as the default projection in imageCollectionConfig.yml NA
latStart/lonStart The UTM lat/lon coordinate for the bottom left corner of the full region. Might be useful to use https://epsg.io/map [or similar] to get an idea of the UTM coordinates needed. m
latSize/lonSize The size of the region in lat/lon axis m
latIntervalSize/lonIntervalSize The region is split into latstep/lonstep intervals. Google Earth images are taken around the central point of each interval. If the latstep/lonstep is not divisble by total region area [latinterval/loninterval], the number of steps will be rounded up. m
horizFov Horizontal field of view of Google Earth tour camera. degrees
range0 Unsure of function- keep to zero [default] No idea
altitudeMode How the height of the camera is determined i.e. for absolute the camera height is measured from a height of zero as opposed to ground level. Best to keep default. NA
lookAtDuration How long does the Google Earth tour camera look at a given location? Default is 1 second. Only play with this if there are issues with google earth. Other elements of the program routine will need to be edited if this parameter is changed. E.g. if changing to 1s then you will need to run the google earth "movie" at 1 fps rather that 10 fps for 0.1s. Best to keep default. seconds
zenithAngles Zenith angle(s) of the camera. 0 degrees looks straight down at the center of each latstep/lonstep. Takes multiple inputs. Use in conjunction with multiple 'nSamplesAroundOrigin' and 'pathLengths' degrees
nSamplesAroundOrigin For each latstep/lonstep, defines the number of images to be taken in equal azimuth angle steps around each zenithAngle. Use in conjunction with 'zenithAngles' and 'pathLengths' NA
pathLengths The path length between the camera and the center of the interval. Use in conjunction with 'zenithAngles' and 'nSamplesAroundOrigin'. m

The 'regionArea' parameters are shown diagramically below: alt text

Images are collected by rotatating a camera around each interval 'nSamplesAroundOrigin' times. Once every image of one interval is collacted, the camera moves to the next, like this:

alt text

Using multiple zenith angles, path lengths and samples around origin

The parameters 'zenithAngles', 'nSamplesAroundOrigin' and 'pathLengths' must all have the same number of inputs. Multiple inputs are given to a parameter like so: 

cameraOptions:
   zenithAngles:
   - 0
   - 45

if you wanted to take images at zenith angles 0 and 45. Correspondingly, nSamplesAroundOrigin and pathLengths must also have 2 arguments in this scenario. For example if you had zenithAngles [0, 45], as above, nSamplesAroundOrigin [1, 10] and pathLengths [360, 260] the Google Earth tour will capture one image at 0 degrees from 360 metres and 10 images at 45 degrees from 260 metres.

Run imageCollection.PS1

Run imageCollection.PS1 to collect all required Google Earth images and calculate their view domains. imageCollection.PS1 creates the imageIntervalTable.csv file within the 'imageInterval' directory. This file contains information on the camera position of all images that will be created. A KML file is also generated that is automatically loaded into Google Earth. Using this KML, a sequence of images of the specified area can be created.

Configure Google Earth

Some advised Google Earth settings:

alt text

Google Earth should automatically open when imageCollection.PS1 is run. Configure Google Earth by:

  1. Clear and then maximise both caches [options.. -> tools -> options...] (with the buttons in the same window).
  2. Close the small time bar in the bottom left corner of the images displayed, by clicking on the small 'x': alt text
  3. Go to 'Tools -> Movie Maker".
  4. The following window will appear:

alt text

  1. You have to use the settings displayed:
    • Save images in the googleEarthOut subdirectory within the region directory you're working in
    • Make sure you select the right kml from the saved tour drop down menu. The tour kml will be called {your project name}_{number of times google earth has run}.kml
    • frames per second (fps) must correspond to the 'lookAtDuration' defined in the config yml file e.g. a look at duration of 0.1s corresponds to a fps of 10.
    • It's recommended that a square picture size is use e.g. 2000 x 2000 pixels.
    • Maximum picture quality is recommended.
  2. Click "create movie"
  3. If Googel Earth crashes, follow the powershell prompts (requires quotes e.g. type "y" not y, see issue #8).

Close Google Earth

Once the tour and image capture has finished, close Google Earth and follow the powershell prompts.

Output files

googleEarthOut

Stores the raw output images from Google Earth. They are sorted into n subdirectories (googleEarthOut\runn), where n is the number of times Google Earth was restarted. This is needed because once Google Earth is restarted, the image number always starts from zero. The first image from the first run is

googleEarthOut\run0\movie-000000.png

The first image from the second run is 

googleEarthOut\run1\movie-000000.png

etc.

imageInterval/imageIntervalTable.csv

This is the original table created by the programme showing every camera position it plans to take a picture from. Column meanings are defined below.

imageInterval/imageViewDomains.csv

This file contains information about each image collected from google earth. The columns have the following meanings:

Header(s) Description
Z, X, Y The height above ground, X and Y positions of the camera.
Zenith, azimuth The zenith and azimuth angles of the camera.
Roll Roll of the camera.
Z_ground The height of the ground at the centre of the interval the camera is looking at.
IntervalCentre The central point of the interval that the camera is focussed on, and the height of this point above sea level [x, y, z].
Created A reference column used by the program.
intervalNo The interval number.
Label, run The name of the image and which 'run' it was created.
central, r1sl, r2sl, r1sr, r1sl The coordinates and above sea level height of the central point, lower left, upper left, lower right and upper right of the image. See below for more details.
r1sl_adjusted, r2sl_adjusted, r1sr_adjusted, r1sl_adjusted As above but after making an adjustment for height.
topography_flag 0 or 1. 0 means no complex topography has been detected and 1 means complex topography has been detected. In this case the calculated view domain of the image is likely to be innacurrate. The user should consider taking a higher density of images if complex terrain is present.

Further details

Image source area calculation

The image source area is calculated to give a representation of the ground area observed by each camera. There are five points of interest with the camera source area. The central point is along the camera axis. The other points are r1sl, r1sr, r2sr, r2sl. See figures below for where these points lie on the image source area.
alt text alt text