plotKML (version 0.5-4)

spPhoto: Generate an object of class "SpatialPhotoOverlay"

Description

spPhoto function can be used to wrap pixel map (pixmapRGB), http://en.wikipedia.org/wiki/Exchangeable_image_file_format{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 http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html{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 http://www.sno.phy.queensu.ca/~phil/exiftool/{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 http://commons.wikimedia.org/wiki/Special:UploadWizard{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 http://www.omegahat.org/Rexif/{Rexif} 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 (http://www.sno.phy.queensu.ca/~phil/exiftool/)
• Wikimedia API (http://www.mediawiki.org/wiki/API)

See Also

getWikiMedia.ImageInfo, pixmap::pixmapRGB, spMetadata

Examples

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