plotKML (version 0.8-3)

spPhoto: 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)

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)

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).

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)
# }