kmlPolygon             package:maptools             R Documentation

_C_r_e_a_t_e _a_n_d _w_r_i_t_e _a _K_M_L _f_i_l_e _o_n _t_h_e _b_a_s_i_s _o_f _a _g_i_v_e_n _P_o_l_y_g_o_n_s _o_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     The function is used to create and write a KML file on the basis
     of a given Polygons object (a list of Polygon objects) for the
     usage in Google Earth resp. Google Maps.

_U_s_a_g_e:

     kmlPolygon(obj=NULL, kmlfile=NULL, 
         name="R Polygon", description="", col=NULL, visibility=1, lwd=1, border=1,
         kmlname="", kmldescription="")
     x <- kmlPolygon(obj=NULL, 
         name="R Polygon", description="", col=NULL, visibility=1, lwd=1, border=1,
         kmlname="", kmldescription="")
     y <- kmlPolygon(kmlname="", kmldescription="")

_A_r_g_u_m_e_n_t_s:

     obj: a 'Polygons' or 'SpatialPolygonsDataFrame' object

 kmlfile: if not 'NULL' the name as character string of the kml file to
          be written

    name: the name of the KML polygon

description: the description of the KML polygon (HTML tags allowed)

     col: the fill color (see also Color Specification) of the KML
          polygon

visibility: if set to '1' or 'TRUE' specifies that the KML polygon
          should be visible after loading

     lwd: the stroke width for the KML polygon

  border: the stroke color (see also Color Specification) for the KML
          polygon

 kmlname: the name of the KML layer

kmldescription: the description of the KML layer (HTML tags allowed)

_D_e_t_a_i_l_s:

     The function is used to convert a given 'Polygons' object (a list
     of Polygon objects) or the first 'Polygons' object listed in a
     passed 'SpatialPolygonsDataFrame' object into KML polygon. If
     'kmlfile' is not 'NULL' the result will be written into that file.
     If 'kmlfile' is 'NULL' the generated KML lines will be returned
     (see also value). 

     The conversion can also handle polygons which are marked as holes
     inside of the Polygons object if these holes are listed right
     after that polygon in which these holes appear. That implies that
     a given plot order set in the Polygons object will *not* be
     considered.

     For a passed 'Polygons' object the function generates a <Style>
     tag whereby its id attribute is set to the passed object's ID.

     The resulting KML polygon will be embedded in
     '<Placemark><MultiGeometry><Polygon>'.

_V_a_l_u_e:

     x is a list with the elements 'style' and 'content' containing the
     generated lines of the KML file as character vectors if 'kmlfile'
     is 'NULL'.

     y is a list with the elements 'header' and 'footer' representing
     the KML file' header resp. footer if 'obj' is 'NULL' (see second
     example).

_C_o_l_o_r _S_p_e_c_i_f_i_c_a_t_i_o_n:

     The following color specifications are allowed: ''red'', '2', or
     as hex code ''#RRGGBB'' resp. ''#RRGGBBAA'' for passing the alpha
     value.

_A_u_t_h_o_r(_s):

     Hans-J. Bibiko

_S_e_e _A_l_s_o:

     'kmlOverlay', 'kmlLine', 'SpatialPolygons'

_E_x_a_m_p_l_e_s:

     data(wrld_simpl)
     ## creates a KML file containing the polygons of South Africa (plus hole)
     sw <- slot(wrld_simpl[wrld_simpl$NAME=="South Africa",], "polygons")[[1]]
     tf <- tempfile()
     kmlPolygon(sw, kmlfile=tf, name="South Africa", col="#df0000aa", lwd=5, 
         border=4, kmlname="R Test", 
         kmldescription="This is <b>only</b> a <a href='http://www.r-project.org'>R</a> test.")
     tf

     ## creates a KML file containing the polygons of South Africa, Switzerland, and Canada
     sw  <- wrld_simpl[wrld_simpl$NAME %in% c("South Africa", "Switzerland", "Canada"),]
     out <- sapply(slot(sw, "polygons"), function(x) { kmlPolygon(x,
         name=as(sw, "data.frame")[slot(x, "ID"), "NAME"], 
         col="red", lwd=1.5, border='black', 
         description=paste("ISO3:", slot(x, "ID"))) })
     tf <- tempfile()
     kmlFile <- file(tf, "w")
     tf
     cat(kmlPolygon(kmlname="R Test", kmldescription="<i>Hello</i>")$header, 
         file=kmlFile, sep="\n")
     cat(unlist(out["style",]), file=kmlFile, sep="\n")
     cat(unlist(out["content",]), file=kmlFile, sep="\n")
     cat(kmlPolygon()$footer, file=kmlFile, sep="\n")
     close(kmlFile)

