R: Generate an object of class '"SpatialPhotoOverlay"'

spPhoto {plotKML}

R Documentation

Generate an object of class `"SpatialPhotoOverlay"`

Description

spPhoto function can be used to wrap pixel map (pixmapRGB), EXIF (Exchangeable Image File format) data, spatial location information (standing point), and PhotoOverlay (geometry) parameters to create an object of class "SpatialPhotoOverlay". This object can then be parsed to KML and visualized using Google Earth.

Usage

spPhoto(filename, obj, pixmap, exif.info = NULL, ImageWidth = 0, 
   ImageHeight = 0, bands = rep(rep(1, ImageHeight*ImageWidth), 3), 
   bbox = c(0, 0, 3/36000*ImageWidth, 3/36000*ImageHeight),
   DateTime = "", ExposureTime = "", FocalLength = "50 mm", 
   Flash = "No Flash", rotation = 0, leftFov = -30, rightFov = 30, 
   bottomFov = -30, topFov = 30, near = 50, 
   shape = c("rectangle", "cylinder", "sphere")[1], range = 1000, tilt = 90, 
   heading = 0, roll = 0, test.filename = TRUE)

Arguments

`filename`	file name with extension (ideally an URL)
`obj`	object of class "SpatialPoints" (requires a single point object)
`pixmap`	object of class "pixmapRGB" (see package pixmap)
`exif.info`	named list containing all available EXIF metadata
`ImageWidth`	(optional) image width in pixels
`ImageHeight`	(optional) image height in pixels
`bands`	(optional) RGB bands as vectors (see `pixmap::pixmapRGB`)
`bbox`	(optional) bounding box coordinates (by default 1 pixel is about 1 m in arc degrees)
`DateTime`	(optional) usually available from the camera EXIF data
`ExposureTime`	(optional) usually available from the camera EXIF data
`FocalLength`	(optional) usually available from the camera EXIF data
`Flash`	(optional) usually available from the camera EXIF data
`rotation`	(optional) rotation angle in 0–90 degrees
`leftFov`	(optional) angle, in degrees, between the camera's viewing direction and the left side of the view volume (-180 – 0)
`rightFov`	(optional) angle, in degrees, between the camera's viewing direction and the right side of the view volume (0 – 180)
`bottomFov`	(optional) angle, in degrees, between the camera's viewing direction and the bottom side of the view volume (-90 – 0)
`topFov`	(optional) angle, in degrees, between the camera's viewing direction and the top side of the view volume (0 – 90)
`near`	(optional) measurement in meters along the viewing direction from the camera viewpoint to the PhotoOverlay shape
`shape`	(optional) shape type — rectangle (standard photograph), cylinder (for panoramas), or sphere (for spherical panoramas)
`range`	(optional) distance from the camera to the placemark
`tilt`	(optional) rotation, in degrees, of the camera around the X axis
`heading`	(optional) direction (azimuth) of the camera, in degrees (0 – 360)
`roll`	(optional) rotation about the y axis, in degrees (0 – 180)
`test.filename`	logical; species whether a test should be first performed that the file name really exists (recommended)

Details

The most effective way to import a field photograph to SpatialPhotoOverlay for parsing to KML is to: (a) use the EXIF tool (courtesy of Phil Harvey) to add any important tags in the image file, (b) once you've added all important tags, you can upload your image either to a local installation of Mediawiki or to a public portal such as the Wikimedia Commons, (c) enter the missing information if necessary and add an image description. Once the image is on the server, you only need to record its unique name and then read all metadata from the Wikimedia server following the examples below.
You can also consider importing images to R by using the pixmap package, and reading the technical information via e.g. the exif package. If the image is taken using a GPS enabled camera, by getting the EXIF metadata you can generate the complete SpatialPhotoOverlay object with minimum user interaction. Otherwise, you need to at least specify: creation date, file name, and location of the focal point of the camera (e.g. by creating "SpatialPoints" object).

Value

Returns an object of class "SpatialPhotoOverlay":

`filename`	URL location of the original image
`pixmap`	optional; local copy of the image (`"pixmapRGB"` class)
`exif.info`	list of EXIF metadata
`PhotoOverlay`	list of the camera geometry parameters (KML specifications)
`sp`	location of the camera (`"SpatialPoints"` class)

Note

The spPhoto function will try to automatically fix the aspect ratio of the ViewVolume settings (leftFov, rightFov, bottomFov, topFov), and based on the original aspect ratio as specified in the EXIF data. This might not work for all images, in which case you will have to manually adjust those parameters.
Dimension of 3/36000*ImageWidth in decimal degrees is about 10 m in nature (3-arc seconds is about 100 m, depending on the latitude).

Author(s)

Tomislav Hengl

References

EXIF tool (http://www.sno.phy.queensu.ca/~phil/exiftool/)
Wikimedia API (http://www.mediawiki.org/wiki/API)

Examples

## Not run: # two examples with images on Wikimedia Commons
# (1) soil monolith (manually entered coordinates):
imagename = "Soil_monolith.jpg"
# import EXIF data using the Wikimedia API:
x1 <- getWikiMedia.ImageInfo(imagename)
# create a SpatialPhotoOverlay:
sm <- spPhoto(filename = x1$url$url, exif.info = x1$metadata)
# plot it in Google Earth
kml(sm, method="monolith", kmz=TRUE)
# (2) PhotoOverlay (geotagged photo):
imagename = "Africa_Museum_Nijmegen.jpg"
x2 <- getWikiMedia.ImageInfo(imagename)
af <- spPhoto(filename = x2$url$url, exif.info = x2$metadata)
kml(af)

## End(Not run)

[Package plotKML version 0.5-9 Index]

Generate an object of class "SpatialPhotoOverlay"