spPhoto {plotKML} | R Documentation |
"SpatialPhotoOverlay"
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.
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)
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 |
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) |
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).
Returns an object of class "SpatialPhotoOverlay"
:
filename |
URL location of the original image |
pixmap |
optional; local copy of the image ( |
exif.info |
list of EXIF metadata |
PhotoOverlay |
list of the camera geometry parameters (KML specifications) |
sp |
location of the camera ( |
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).
Tomislav Hengl
EXIF tool (http://www.sno.phy.queensu.ca/~phil/exiftool/)
Wikimedia API (http://www.mediawiki.org/wiki/API)
getWikiMedia.ImageInfo
, pixmap::pixmapRGB
, spMetadata
## 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)