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

In plotKML: Visualization of Spatial and Spatio-Temporal Objects in Google Earth

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 (https://exiftool.org/)

• Wikimedia API (https://www.mediawiki.org/wiki/API)

See Also

getWikiMedia.ImageInfo, pixmap::pixmapRGB, spMetadata

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)

plotKML documentation built on June 7, 2022, 5:07 p.m.